WSL2-Bootstraper: One-Click Ubuntu 24.04 Dev Environment on Windows

Spinning up a clean Linux dev box on Windows usually means juggling Microsoft Store installs, manual package tweaks, and a dozen mismatched blog tutorials.
wsl2-bootstraper compresses all that into a single PowerShell command.

TL;DR: From zero to a Docker-, Python-, and Zsh-ready Ubuntu 24.04 in ~5 minutes.

Repo → https://github.com/ramkrishs/wsl2-bootstraper

1 Prerequisites

Windows 10/11 with WSL enabled
PowerShell 5.1+ (run as Administrator)

2 Installation & Usage

⚡ One-Click (recommended)

irm https://raw.githubusercontent.com/ramkrishs/wsl2-bootstraper/main/setup-wsl.ps1 | iex

You’ll be prompted for:

UNIX username / password
Git name / email
Optional components to enable
- Docker ✅
- Zsh + Oh My Zsh ✅
- CUDA ❌ (optional)
- systemd ✅

⚙️ Manual

git clone https://github.com/ramkrishs/wsl2-bootstraper.git
cd wsl2-bootstraper
.\setup-wsl.ps1

Same prompts, same idempotent flow—just local.

3 What the Script Actually Does

| Layer         | Action                                                      |
| ------------- | ----------------------------------------------------------- |
| **WSL**       | Checks / installs Ubuntu 24.04; converts to WSL 2 if needed |
| **User**      | Creates sudo-enabled UNIX user; sets as default (registry)  |
| **systemd**   | Writes `/etc/wsl.conf` & enables daemon                     |
| **Dev tools** | `build-essential`, `curl`, `git`, `ripgrep`, `fzf`          |
| **Python**    | Installs pyenv, latest 3.12.x, `pipx`, `poetry`, `uv`       |
| **Docker**    | Installs & sockets into WSL engine (if selected)            |
| **Zsh**       | Oh My Zsh + Powerlevel10k theme & common plugins            |
| **CUDA**      | Driver + toolkit (optional flag)                            |
| **Final**     | Optionally opens Ubuntu terminal when finished              |

Everything runs inside an **embedded Bash payload** so Windows paths stay out of `$HOME`.

4 Idempotency & Safety

Re-runs cleanly—no duplicate users, no broken links.
Passwordless-sudo lines are appended exactly once.
Guard-rails around $HOME paths to avoid Windows contamination.
Registry & /etc/passwd checks ensure the default user sticks.

5 Troubleshooting Cheatsheet

| Symptom                     | Fix                                                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Default user stays **root** | Verify **`DefaultUid`** in `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}` matches `id -u $USER`. |
| `pyenv` not loading         | Confirm the `.zshrc` stanza below exists **after** your plugin block.                                          |
| WSL RAM keeps ballooning    | Create `%UserProfile%\.wslconfig` → <br>`[wsl2]`<br>`memory=6GB` then `wsl --shutdown`.                        |

| CUDA missing | Re-run script and choose CUDA; ensure you’re on a GPU-capable Insider build. |

.zshrc insert (should be automatic):

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
export PATH="$HOME/.local/bin:$PATH"

6 Known Issues

Password input must not contain special PowerShell-escaped chars ($, `, ")
If Docker Desktop is already installed, disable its WSL integration to avoid port clashes.
systemd + WSLg sometimes breaks on Insider builds—toggle systemd true/false in /etc/wsl.conf and restart.

7 Contribution

PRs welcome—please:

Stick to ASCII-only PowerShell
Preserve idempotency (rerun tests)
Add coverage for path-injection & .zshrc edits

Final Words

wsl2-bootstraper exists because a fresh dev environment should be one command away, not an afternoon lost to doc hunting. Give it a spin, file an issue, or open a PR—let’s keep Windows-to-Linux onboarding painless.

💬 Questions or ideas? Connect on LinkedIn or follow build-logs on Substack.