Complete guide to creating environments with WSL2 + Docker + VS Code

If you work on Windows and want a solid development environment with Linux, containers, and a modern editor, WSL2, Docker, and VS Code form a winning trioThis combo allows you to program on Linux without leaving Windows, run containers quickly, and debug projects comfortably, all on the same machine.

The idea is simple: Take advantage of the WSL2 Linux kernel, add Docker (either via Docker Desktop or by installing the native engine on the distro) and finish with VS Code and Dev Containers to obtain reproducible environments. In the following sections you will see step by step how to set it up, with Practical recommendations, shortcuts, real-life cases and solutions to typical problems.

Containers and why they fit with WSL2 + VS Code

Docker allows you to package applications with everything you need to run the same on any machine. Unlike a traditional VM, containers share the host kernel, They start faster and consume less. In addition, they facilitate continuous availability: you upload a new version of the container and replace the entire system without stopping.

With WSL2, Windows comes with a real Linux kernel built in. Thanks to this, Linux containers run natively on your computer, and if you use Docker Desktop with WSL 2 backend you can run Linux and Windows containers side by side. This combines performance, compatibility and unified workflow.

System Requirements and Preparation

First, it's a good idea to check that Windows meets the requirements for WSL2 and Docker Desktop. Check Windows versions and builds (Win + R, type “winver”) and keep in mind that Docker Desktop has specific system and licensing requirements (free for personal use and small businesses).

To install WSL2 using the simplified method, open PowerShell o CMD with permissions and executes wsl --installThis command enables the necessary components, installs the Linux kernel, sets WSL 2 as the default, and downloads Ubuntu by default. Reboot when prompted.

After installation, open the distro (Ubuntu if you haven't changed) and create your Linux username and password. Remember that while you type the password you won't see any characters: this is normal. This account will be the default and will be able to run sudo for administrative tasks.

Keep the distro up to date with sudo apt update && sudo apt upgrade. Windows does not automatically update the distribution, so you decide whenIf you want to add more distros, you can do so from the Microsoft Store or by importing images.

Terminal, storage, and editor: first decisions

Install Windows Bus Terminal for a modern experience with tabs, panels, and themes. Manages multiple lines of commands painlessly and customize to your liking. Every time you add a WSL distro, its corresponding profile will appear in the terminal.

When it comes to project files, performance is key: If you use Linux tools, save projects to the WSL2 file system. (for example, \\wsl$\Ubuntu-22.04\home\tuusuario\proyecto). It can be accessed from both sides, but Working in /mnt/c with Linux tools may be slower.

To open the current WSL folder in Explorer, run explorer.exe . (includes the period). And to open the folder in VS Code from WSL, use code .. With the correct extension, VS Code connects to the extension server within WSL and you forget about strange routes and binary problems.

Install Docker Desktop with WSL 2 backend

A very convenient route is to use Docker Desktop. Download, install, and activate it. «Use the WSL 2 based engine» in Settings > General. Then, in Settings > Resources > WSL Integration, choose WSL2 distros where you want to enable the integration.

Verify the installation from your distro with docker --version and try with docker run hello-world. If all goes well, you will have Linux containers running on top of the WSL2 kernel and managed by Docker Desktop in Windows.

Docker Desktop creates two special WSL distributions for storage and service: docker-desktop y docker-desktop-data. You will also see their routes as \\wsl$\docker-desktop y \\wsl$\docker-desktop-data. If you need to locate your data from Windows, you can open a WSL shell and run explorer.exe ., or navigate to \\wsl\<Distro>\mnt\wsl.

If you come from a Docker old preview for WSL, there may be a deprecated context called "wsl". Check it with docker context ls; if it appears, remove it with docker context rm wsl To avoid errors like "open \\.\/pipe\/docker_wsl". In the current integration you should use the default context.

Developing in remote containers with VS Code

To work comfortably with containers, install the extensions in VS Code WSL, Dev Containers y Docker. With them, you will be able to open your WSL project in VS Code, and also reopen the folder inside a development container with the whole stack ready.

Practical example (Django). From your WSL terminal, clone a repository, such as a Django “Hello World” repository: git clone https://github.com/mattwojo/helloworld-django.git, enter with cd helloworld-django and open VS Code with code .. Check the green WSL remote connection indicator in the lower left corner.

Open the palette (Ctrl + Shift + P) and choose “Dev Containers: Reopen in Container” (or “Open Folder in Container…” if you are coming from Windows using \\wsl$). Select an appropriate definition (e.g. Python 3 for Django). VS Code will generate a folder .devcontainer Dockerfile y devcontainer.json, will build the image and will raise the development container.

Open the integrated terminal and run uname to confirm that you are on Linux, and python3 --version to see the Python version of the container. To debug, go to the Run and Debug view, create the launch.json choosing the framework configuration (Django in this case) and press F5. Open the URL that the terminal tells you (for example, http://127.0.0.1:8000).

Dev Containers and Codespaces: Reproducible Environments

A Dev Container is defined with .devcontainer/devcontainer.json and, optionally, a Dockerfile. This approach allows use base images or other custom images, pre-install dependencies, configure VS Code extensions, and automate post-configuration commands.

Among the most common use cases are those of Collaborative Data Science (with Python, Jupyter, pandas, seaborn and a homogeneous set of dependencies) and those of Node.js backend with PostgreSQL coordinated with docker-compose.yml. In this way, the entire team works with the same environment, no surprises due to local differences.

The same folder .devcontainer Works in the cloud with GitHub Codespaces: When you create a Codespace, GitHub automatically builds the environment. This promotes frictionless switching between on-premises and cloud, reproducibility and rapid incorporation of new collaborators.

Best practices: consider official base images devcontainers/, version the folder .devcontaineruse postCreateCommand to automate installations and combines devcontainer.json docker-compose.yml when you need multiple services.

Alternative: Docker without Docker Desktop (native engine in WSL2)

If you prefer to avoid Docker Desktop (due to company policy or personal choice), you can install the Docker engine directly on your WSL2 distro. Add the GPG key, official repository, and packages (on Ubuntu):

Follow these commands to add the key and repository: # Clave oficial y repositorio
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https:\/\/download.docker.com\/linux\/ubuntu\/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo «deb [arch=$(dpkg –print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https:\/\/download.docker.com\/linux\/ubuntu \n$(. \/etc\/os-release && echo «$VERSION_CODENAME») stable» |
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group to use the CLI without sudo: sudo usermod -aG docker $USER. Close and reopen WSL. Check with docker run hello-world. For autostart you can use /etc/wsl.conf [boot] y command = service docker start, systemd if already enabled on your WSL2 (on recent versions).

Network and ports: from Windows you can access containers published in localhost thanks to WSL2. If you need to expose WSL2 services to your local network (e.g., access from mobile), Use a port proxy on Windows with Netsh and creates the corresponding firewall rule. A script Typical PowerShell gets WSL IP, configures portproxy and add the rule; this way you avoid repeating commands after reboots.

Why choose this route? You avoid relying on Docker Desktop licenses or policies and control every piece. As a complement, you can deploy carrier To manage containers with the web interface: create a volume and launch the container with ports 8000 and 9443; access https://localhost:9443 (accepts the certificate), creates the admin user and Manage your Docker with clicks.

Git, SSH, and where to clone code

In WSL2 you can clone with Git in your directory Linux home and work with VS Code. This is usually the most convenient option: better performance and less frictionIf you prefer to clone from a container, you will need to manage credentials and keys. SSH inside the container or mount your ~/.ssh carefully.

GUI for Git? Tools like Sublime Merge or GitKraken can work in this scenario. GitKraken can even open from the WSL terminal and display on Windows, having access to WSL files. For SSH with GitLab or other remotes, set up your keys in WSL and check permissions and SSH agents before cloning via SSH.

Remember the performance tip: avoid /mnt/c for your code if you are going to compile or use intensive Linux tools. Use \\wsl$ from Windows to access the same folder whenever you need it.

Terminal Productivity: ZSH, Oh My Zsh, Powerlevel10k, Antigen, FZF, and Tmux

For a comfortable and powerful terminal, install ZSH sudo apt install zsh and change it to default with chsh -s $(which zsh). Then install Oh my zsh with its official script and give it an advanced look and functionality.

The issue Powerlevel10k adds a highly configurable prompt with Git integration and excellent performance. Install it from its repo, place ZSH_THEME="powerlevel10k/powerlevel10k" en ~/.zshrc and follow the wizard to adjust fonts and appearance. You will see your repo, branch and more status take a look.

With antigen You will manage ZSH plugins declaratively. Useful packages: zsh-autosuggestions, a plugin for fzf, support zsh-npm-scripts-autocomplete y zsh-z to jump between directories. Add NVM as a plugin or officially for hot-switch Node versions.

Improves flow with Beat y fd from apt (bat y fd-find in Ubuntu), and configure fzf for searches: Ctrl + R for history, Alt + C for folders and Ctrl + T for files with color preview. Immediate time savings In day to day.

To multiplex the terminal, use tmux (sudo apt install tmux) and its plugin manager TPM. With proper setup you'll have themes, session recovery (resurrect/continuum), integration with Vim-like navigation and shortcuts to split panels. Install plugins with Ctrl + Espacio and then I (capital i) within Tmux.

Databases, GPUs, and graphics applications

Your project may need a database. You have guides for MySQL, PostgreSQL, MongoDB, Redis, SQL Server or SQLite running within WSL or as containers. Integrate services in docker-compose.yml y Get your Dev Container online to them without complications.

GPU acceleration? WSL2 offers support for machine learning workloads using the GPU, with special focus on NVIDIA and CUDA. On AMD/Intel cards there are alternative paths; check your manufacturer's documentation for enable acceleration.

WSL2 allows you to run Linux GUI applications on Windows. For specific cases, You can open Linux editors or graphical tools and will be displayed in Windows windows. If you see glitches, restart WSL2 with wsl --shutdown usually fixes it.

Interoperability and useful commands

WSL and Windows understand each other well. From PowerShell, run Linux commands wsl, For example: wsl ls -laYou can also mix: wsl ls -la | findstr "git" o dir | wsl grep git to filter between worlds.

From Linux run Windows tools by adding .exe: notepad.exe .bashrc. Also useful combinations: ipconfig.exe | wsl grep IPv4 | wsl cut -d: -f2 to keep the IP. Everything flows between both systems.

To mount external drives in WSL2, follow the disk mounting guide. You'll be able to access to USB or additional discs and work with them from Linux.

Network, ports and localhost

WSL2 maps automatically the ports of the Linux environment to localhost in Windows. That is, if you publish a -p 3000:3000 In Docker, you can enter http://localhost:3000 from your browser on Windows without doing anything else.

If you want to expose WSL2 services to the LAN (another device on your network), you can use a PowerShell script that obtains the IP of WSL and invokes netsh interface portproxy to forward ports, in addition to creating the firewall rule with New-NetFirewallRule. This automates publishing and avoid manually repeating steps after reboots.

Common problems and how to solve them

Deprecated Docker contexts in WSL: If you see one named “wsl” inherited from older previews, delete it with docker context rm wsl. This way you will avoid mistakes like open \\.\/pipe\/docker_wsl and you will stay with it default context.

Where does Docker store data under WSL? Search \\wsl$\docker-desktop y \\wsl$\docker-desktop-data, or open your distro and launch explorer.exe . to navigate. You also have \\wsl\<Distro>\mnt\wsl to see related storage.

GUI window glitches launched from WSL: sometimes the apps Electron-based models show artifacts. Restart WSL2 with wsl --shutdown and try again. Microsoft is correcting these details with There.

No systemd? In recent iterations, WSL2 can enable systemd by default; if this is not your case, you can start services with /etc/wsl.conf and the section [boot]. Check your version and documentation if you need background services.

You upgraded from WSL1 to WSL2 and Docker doesn't cooperate: sometimes there are remnants of old configurations like DOCKER_HOST=tcp://localhost:2375. If you are coming from that setup, uninstall Docker completely on Windows and WSL (packages, paths and configuration files), and reinstall Docker Desktop with WSL 2 backend. Check with wsl -l -v that exist docker-desktop y docker-desktop-data in version 2.

If you are using the native engine in WSL2 without Desktop and exposing the daemon over TCP, remember that without TLS it is insecure. This setup is for local development environments, not production. Make sure you have a good handle on your network and avoid unnecessary open ports.

Final tips and best practices

In projects with docker-compose.yml that assume Docker Desktop automations (mounts and network aliases), adjust absolute paths if you see volumes with ~ and adds extra_hosts host.docker.internal:host-gateway if your stack requires it. Small changes avoid surprises.

For VS Code, the WSL + Dev Containers + Docker combo allows you work inside the container with the same extensions and editor settings. It's a way to standardize the environment among team members and reduce the "it works on my machine" factor.

If you prefer a Docker Desktop-free approach, the native engine in WSL2 offers granular control and, with Portainer, a lightweight management interface. Both routes are valid and will depend on your needs, licenses and internal policies.

You have a complete map: Install and configure WSL2, choose between Docker Desktop or native engine, work with Dev Containers and VS Code, use databases and GPU, and boost your productivity with a tuned terminal and Tmux. The key is to combine these pieces according to your project and team to achieve a reproducible, fast and comfortable environment In day to day.