Setting up a development environment with WSL on Windows

If you program in Windows and want to enjoy the tools and workflows of Linux without heavy virtual machines or Boot dual, WSL is your best allyWith the Windows Subsystem for Linux, you can install distributions like Ubuntu, Debian, or openSUSE and run utilities, shells, and servers as if they were on native Linux, but integrated with Windows.

In this guide I explain, step by step, how to set up a modern development environment with WSL: quick installation, distribution selection, WSL version management, username and password, good storage practices, Terminal, VS Code/Visual Studio, Git, Docker, databases, GPU acceleration, Linux graphical apps and key commands.Plus, you'll learn how to customize your shell with Zsh and manage Node.js with nvm to work with multiple versions without the hassle.

Prerequisites and Windows version check

WSL runs natively on Windows 10 version 2004 (build 19041) or higher and on Windows 11. If you are not sure of your version, press Windows + R, type winver and confirm that your build is compatible.

To use the simplified installation command wsl --install It is recommended to have recent builds (Windows 10 20262+ or current Windows 11)If you're missing an update, you can do so from Settings or with the Windows Update Assistant.

If your computer does not support WSL 2, enable virtualization in the BIOS/UEFI and make sure the "Virtual Machine Platform" feature is available in Windows.On computers coming from older manual installations, you may need to update the WSL Linux kernel.

Ultra-fast WSL installation

The most direct way is to open PowerShell o Symbol of the system as administrator and run:

wsl --install

This command enables the WSL and Virtual Machine Platform components, downloads the Linux kernel, sets WSL 2 as default, and installs Ubuntu automatically.. Windows may prompt you to restart to complete the installation.

If you prefer another distribution, you can specify it in the installation with:

wsl --install -d <NombreDeLaDistro>

To view the catalog available online use:

wsl --list --online

On older computers or if you want fine-grained control, you have the option to follow the manual installation from Windows Features or import a TAR with a custom distro. Still, for most users, the shortcut with --install It is the most comfortable way.

First boot: Linux username and password

After installation, open the distro from the Start menu (Ubuntu by default) and create your Linux username and password.. These credentials are independent of your Windows account.

The password is typed “blindly” (you won’t see anything when typing), this is completely normal.. Once created, your account will be the default and will have administrative permissions through sudo.

Remember that each distribution has its own accountsIf you install, reinstall, or add new distros, you'll repeat this process for each one.

Forgot your password? Open PowerShell and enter as root on the default distro:

wsl -u root

If you need another specific distro, please indicate its name.:

wsl -d Debian -u root

Within the root session reset the user's password with:

passwd <usuario>

When you see the password updated successfully message, exit with:

exit

Package Updates and Maintenance

Windows does not automatically update your distro packages, so it's a good idea to do so from time to time.. On Ubuntu/Debian:

sudo apt update && sudo apt upgrade

Keeping your system up to date saves you from silly mistakes and compatibility issues with development tools.. It is a basic routine recommended after the first start.

Choosing, adding, and managing distributions

You can install distros from the Microsoft Store, with wsl --install -d or import them in TAR format for custom scenarios. WSL doesn't limit the number of distros: use as many as you need.

To list installed distros and see their WSL version (1 or 2), run:

wsl -l -v

If you want new installations to use a specific version by default:

wsl --set-default-version 2

To change the version of a specific distro:

wsl --set-version <NombreDistro> 2

You can also choose which distro is used by default when invoking wsl:

wsl -s <NombreDistro>

And to boot a specific distro directly without changing the default:

wsl -d <NombreDistro>

Windows Terminal: The ideal multi-console experience

Windows Terminal brings tabs, panels, GPU acceleration, Unicode/UTF-8, and customization of shortcuts, colors, and themes. If you are going to live with several shells (PowerShell, CMD, various WSL distros, Azure CLI…), you will find it very comfortable.

Every time you install a new distro, Windows Terminal will detect it and you can fine-tune its profile to your liking.. It's the perfect match for WSL if you work with multiple command lines.

File storage and performance

Open the current WSL directory in File Explorer with:

explorer.exe .

Golden rule: save projects in the file system of the OS whose tools you will useIf you're working with Linux tools (gcc, node, python, etc.) from the WSL terminal, save to the WSL FS.

Recommended routes in WSL:

• WSL: \\wsl$\<NombreDistro>\home\<Usuario>\Proyecto
• Evita: C:\Users\<Usuario>\Proyecto o /mnt/c/Users/<Usuario>/Proyecto if you compile/run with Linux tools due to the performance impact.

Cross-access between Windows and Linux exists, but it can severely penalize performance in intensive tasks.. Adjust where you save based on your workflow.

Code editor: VS Code and Visual Studio

Visual Studio Code with the Remote Development extension turns WSL into a complete development environment. Once installed, from the distro terminal open your project with:

code .

You will work “inside” the distro with the entire ecosystem of extensions, debugging, and integrated terminal. Additionally, you can jump between environments (WSL, SSH or containers) in seconds.

For cross-platform C++, Visual Studio 2022 integrates CMake projects with WSL and SSH connections in the same instance.If your stack is native C++, it's worth it.

Git and credential management

Install Git on the distro and configure name and email:

sudo apt install -y git
git config --global user.name "Tu Nombre"
git config --global user.email "tu@correo.com"

In hybrid Windows/WSL projects, rely on the Windows Credential Manager and/or VS Code's built-in capabilities.. Also check the handling of line endings (LF/CRLF) and your .gitignore to avoid surprises.

Containers with Docker in WSL 2

Docker Desktop integrates with WSL 2, allowing you to run Linux containers with near-native performanceYou can open the project as “Remote – Containers” from VS Code and develop within the container.

This setup makes it easy to build teams with reproducible environments and isolate dependencies without messing up the base distro.. Ideal for complex stacks or microservices.

Databases in WSL

WSL is a perfect environment to set up MySQL, PostgreSQL, MongoDB, Redis, SQLite or even SQL Server for Linux. Install them from your distro's package manager or by following the official guides for each engine.

By working the app and the base within WSL you reduce latencies and avoid compatibility issues between OS.If you need to expose ports to Windows, you can connect from native clients without any complications.

GPU acceleration and demanding workloads

WSL allows you to leverage your computer's GPU to accelerate computing tasks, such as training machine learning models.. With the drivers suitable and WSL 2, you will notice clear improvements in performance.

If your work involves CUDA, TensorFlow, PyTorch, or OpenCL, check the driver and version requirements.. Worth it if your stream is GPU intensive.

Linux GUI Applications on Windows

WSL supports graphical Linux applications, so you can open editors or utilities with a front-end directly in Windows.. It's convenient for niche tools that only exist on Linux.

Window integration is seamless: they behave like desktop apps within Windows.. Useful for flows where you combine CLI with specific GUI utilities.

Essential Commands and Windows/Linux Interoperability

One of the great advantages of WSL is combining commands from both worlds into a single line.Some useful examples:

• List with Linux from PowerShell: wsl ls -la
• Mixing Linux and Windows: wsl ls -la | findstr "git" o dir | wsl grep git
• Open Windows Tools from WSL: notepad.exe .bashrc
• Filter IP with cross-utilities:
  • In Bash: ipconfig.exe | grep IPv4 | cut -d: -f2
  • In PowerShell with WSL: ipconfig.exe | wsl grep IPv4 | wsl cut -d: -f2

To change distros on the fly from Windows without altering the default, remember that wsl -d <NombreDistro> open that punctual distribution. If you want to exit an embedded session, type exit.

Mount external or USB drives in WSL

WSL 2 allows mounting external drives, USB or Linux partitions. Once you have identified the route, you can mount it with the command mount from WSL and work with its content.

It is convenient for copying data, analyzing disks or reusing development media without leaving the environment.. Dismount when finished to avoid blockages.

Ways to open and switch between your distributions

You can launch the distro from the Start menu (type, for example, “Ubuntu”), from PowerShell/CMD by typing its name or with wsl.exe to open the default. Adjust the method to what is most comfortable for you.

For quick information on the status of WSL, use wsl [comando] from Windows, for example wsl -l -v to list distros and versions or wsl pwd to see the current route mounted.

WSL Previews and Updates

If you like what's new, you can join Windows Insider (Dev, Beta, or Preview Channel) to receive the latest WSL features.Stability varies by channel, choose based on your needs.

Without changing channels you can try the WSL preview with:

wsl --update --pre-release

See the WSL release notes for changes and requirements for each build.In work environments, assess the risk before testing previews.

Customize your terminal: Zsh, Oh My Zsh and themes

For a more productive experience, install Zsh and Oh My Zsh with themes and plugins that improve autosuggest, coloring, and prompting.. On Ubuntu/Debian:

sudo apt update && sudo apt install -y zsh curl git

Make Zsh your default shell:

chsh -s $(which zsh)

Install Oh My Zsh (via curl):

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

For the topic Powerlevel10k:

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Activate it by editing ~/.zshrc and establishing:

ZSH_THEME="powerlevel10k/powerlevel10k"

Recommended plugins: adds in plugins=(...) de ~/.zshrc:

• git
• zsh-autosuggestions

git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

• zsh-syntax-highlighting

git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

After saving changes in ~/.zshrc, restart the terminal or run source ~/.zshrc to apply settings. Adjust fonts and symbols if the theme requires it.

Node.js on WSL 2 with nvm (multiple versions)

To work with multiple versions of Node.js without conflicts, use nvm (Node Version Manager). Install nvm with:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Cierra y abre la terminal o:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

Install Node.js (LTS or a specific version) and check versions:

nvm install --lts
node -v
npm -v

List and swap versions whenever you need to:

nvm ls
nvm install 22
nvm alias default 22
nvm use 22

With nvm you avoid “breaking” projects when changing versions and you maintain a clean environment for each app.If you're using VS Code, it will integrate with the version active in the terminal.

Basic Bash commands to get your bearings

A quick review of common utilities will save you time if you are just starting out on the command line.:

• pwd: shows the current route.
• ls, ls -a, ls -l: lists files and options.
• cd, cd .., cd ~: navigate between directories.
• mkdir y touch: creates folders and files.
• cat: displays the contents of a file.
• rm: delete files/folder (careful, there is no trash can!).
• history y !número: Review and repeat previous commands.
• clear: clear the screen.

With these basic notions you will be able to move with confidence and focus on your project as soon as possible.Daily practice is what solidifies these shortcuts.

Diagnosing and solving common problems

Si wsl --install If this fails, check for Windows updates, that virtualization is enabled, and that you can activate “Virtual Machine Platform”. In legacy scenarios, install/update the WSL kernel manually.

If the distro doesn't boot or hangs, try restarting WSL with:

wsl --shutdown

For issues with permissions or paths between systems, check where you store your code and avoid working with Linux tools on /mnt/c If you're looking for performance, it also helps to check for antivirus software that might interfere.

With all of the above, you now have a solid foundation for a powerful Windows development environment with a Linux soul, from installing and maintaining WSL to integrating with VS Code/Visual Studio, Git, Docker, and databases, including GPU acceleration, graphical apps, and a fine-tuned terminal with Zsh. From here, all that's left is to adapt the details to your stack and start producing.