Integrating WSL2 with Docker on Windows: A Practical and Complete Guide

If you work in Windows and want to develop as if you were in Linux, the pair formed by WSL 2 and Docker It's one of the best things you can install on your computer. With this integration, you'll get Linux and Windows containers on the same machine, reduced resource consumption, and a... Boot much faster than with other heavier options.

In the following lines you will find a complete guide to fine-tuning Docker Desktop with WSL 2 backendOr, if you prefer, you can run Docker directly within WSL 2 without relying on Docker Desktop. You'll also learn how to leverage it with Visual Studio Code, get performance tips, storage paths, and find a troubleshooting section with common errors and their solutions.

Containers and WSL 2: What you need to know

Docker packages applications and their dependencies into containers so that run the same in any environmentUnlike a classic VM, a container does not need a complete operating system: it shares the host kernel and only adds what your app does not already have available, reducing size and speeding up execution.

Compared to a virtual machine, this approach saves memory and CPU because It doesn't boot an entire OSOn Windows, WSL 2 provides a real Linux kernel with system call support, so Docker can run natively with very solid performance.

Another key advantage is continuous availability. Thanks to containers and orchestrators like Kubernetes, you can Update services by version, replace containers while hot and maintain several revisions as backup without taking down the entire system.

In summary, Docker promotes consistent environments, minimizes dependency conflicts, and accelerates deployments. Combined with WSL 2 on Windows, You get a Linux workflow without leaving your desktop, with automatic integration of files and ports exposed to localhost.

Windows prerequisites

Check that your Windows 10/11 meets the minimum requirements: 64-bit, virtualization enabled in the BIOS/UEFI and at least 4 GB of RAM. In modern builds, simply enabling WSL and its virtualization platform is sufficient.

To activate the components from PowerShell As an administrator, you can use commands in the style of Enable WSL and the Virtual Machine PlatformOn updated equipment, the process is simplified with WSL:

wsl --install

If you already had WSL, sets WSL 2 by default and verify or migrate your installed distributions:

wsl --set-default-version 2
wsl -l -v
wsl --set-version Ubuntu 2

To choose the default distro you will integrate with, you can change the default value when you need it:

wsl -s Ubuntu

Install Docker Desktop with a WSL 2-based engine

The most direct route to a polished environment is to use Docker Desktop with WSL 2 backendDownload the Docker Desktop installer for Windows, run it, and follow the wizard. If your system supports it, the use of the WSL 2 engine will be selected or you will be prompted to enable it during installation.

After starting Docker Desktop, open its panel of Settings And in the General section, enable the WSL 2-based engine option if it isn't already enabled. This will allow you to run Linux containers from Windows without traditional Hyper-V.

Then, enter Settings > Resources > WSL Integration and enable integration for the WSL 2 distribution(s) you will be using (for example, Ubuntu). If the WSL integration tab does not appear, verify that you are in Linux containers mode and not Windows containers mode.

To verify that everything is in place, open your WSL distro (for example, Ubuntu) and execute the verification commands:

docker --version
docker run hello-world

This confirms that the CLI binary and the daemon They respond. If you can pull the hello-world test image, the integration is working.

Developing in containers with Visual Studio Code

With WSL 2 and Docker up and running, the development experience is greatly enhanced with Visual Studio Code and three official extensions: WSL, Dev Containers, and Docker. Each one contributes a piece of the puzzle for working with containers from Windows.

Install the WSL extension to open folders from your distro directly in VS Code. This way you won't have to struggle with paths. incompatible binaries or permission issues between systems.

Install Dev Containers to open the project folder in a container and develop with it environment defined in a Dockerfile and a devcontainer.json file. It's a convenient way to standardize team tools and dependencies.

Also install the Docker extension to compile, run, and manage images, containers, and volumes from within the Docker itself. VS Code sidebarIt makes daily life much easier without leaving the editor.

A typical workflow would be: clone the project in WSL, open it with code .and launch the Dev Containers action in the command palette to Reopen in containerVS Code will generate a .devcontainer folder with your Dockerfile and devcontainer.json appropriate to your stack (e.g., Python/Django) and build the image.

Verify that you are still running Linux in the terminal integrated with VS Code: uname y python3 --versionYou will see Linux (WSL 2) and the version of Python defined by the container, which may differ from the one you have in the distro. With the configuration of Run and Debug (for example, Django profile), you will be able to run and debug your application in the container, accessing the local URL that I indicate, usually http://127.0.0.1:8000/.

Running Docker without Docker Desktop: Direct installation in WSL 2

If you want to avoid Docker Desktop due to licensing or preferences, you can Install Docker Engine within your WSL 2 distroIn Ubuntu, update packages, add the official repository, and proceed with the installation of the necessary components:

sudo apt update && sudo apt upgrade

source /etc/os-release
curl -fsSL https://download.docker.com/linux/${ID}/gpg | sudo apt-key add -
echo "deb [arch=amd64] https://download.docker.com/linux/${ID} ${VERSION_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

To avoid having to precede each command with sudo, add your user to the group. docker and restart the distro session:

sudo usermod -aG docker $USER

The demon starts when you need it within WSL 2 with:

sudo dockerd

If you see a message like this API listen on /var/run/docker.sockThe server is running. Open another terminal on the distro and test that everything is responding with:

docker run --rm hello-world

Using the Docker CLI from Windows with Docker in WSL 2

To invoke Docker and Docker Compose from the Windows side while the daemon lives in WSL 2, download docker.exe and docker-compose.exe Add them to your Windows user PATH. This will allow you to run commands from PowerShell or VS Code in Windows terminals.

You can create a script Use PowerShell to obtain the IP address of the WSL 2 distro and start the daemon listening on TCP, setting the environment variable DOCKER_HOST in Windows. An example of a workflow could be:

$ip = (wsl sh -c "hostname -I").Split(" ")[0]
$DOCKER_HOST = "tcp://" + $ip + ":2375"
[System.Environment]::SetEnvironmentVariable('DOCKER_HOST',$DOCKER_HOST,[System.EnvironmentVariableTarget]::User)
wsl sh -c "sudo dockerd --tls=false -H tcp://$ip"

You will see warnings indicating that opening the daemon without TLS is unsafeThis configuration is exclusively for local development; do not use it in production. You can try the following in another PowerShell window:

docker version
docker container ls
docker run --rm hello-world
docker run -it --rm -p 8080:80 uzyexe/tetris

If you need to orchestrate multiple services, docker-compose will still work. For example, with a sample file you could launch an app with a database and verify port mapping accessing localhost on the port you have exposed.

Common settings in docker-compose without Docker Desktop

When you work without Docker Desktop, some automations are no longer available, so it's advisable to adjust two things in your docker-compose.yml:

• In volumes that use the accent mark for home ~Replace it with your actual home path in WSL 2, for example /mnt/c/Users/tu-usuario if you are pointing to files in C: from the distro.
• Add the section extra_hosts when your project depends on the alias host.docker.internal:

extra_hosts:
- host.docker.internal:host-gateway

This helps you avoid connectivity surprises between containers and the host. replicating facilities that Docker Desktop offers as standard.

Performance and best practices with WSL 2

Docker Desktop on WSL 2 usa dynamic memory allocationconsuming only what is necessary and accelerating intensive operations such as builds. Furthermore, the daemon's cold start is significantly faster than with alternatives based on conventional VMs.

The golden rule: keep your project files within the WSL 2 file systemWork from /home/tu-usuario In this distro, avoid the I/O penalties that appear when mounting Windows paths under /mnt/c for tasks with a lot of disk access.

In Docker Desktop, make sure you have active Use WSL 2 based engine And enable the correct distro integration in Settings > Resources > WSL Integration. If you do this and move your projects to the correct path, the difference in performance is very noticeable.

If you need more isolation due to corporate policies, consider using the mode Hyper-V in Docker Desktop or enable Enhanced Container Isolation. For most development scenarios, WSL 2 offers an excellent balance between performance and simplicity.

Storage folders and useful shortcuts

Docker Desktop creates two internal WSL distributions for your data: docker-desktop y docker-desktop-dataYou can access its folders from Windows using UNC paths if you need to inspect the contents.

A handy trick: from your WSL distro launch explorer.exe . To open the current directory in File Explorer, you can also navigate directly to persistent mount points with:

\\wsl$\<Distro>\mnt\wsl

Replace by the name of your distribution, such as Ubuntu-24.04, to find the internal locations where WSL displays its volumes and where Docker Desktop stores data when working on WSL 2.

Troubleshooting common problems

If you're coming from previous versions of the integration, you might still have an old Docker context called wsl that you already have. not usedCheck your contexts and delete them to avoid errors:

docker context ls
docker context rm wsl

This outdated context can cause error messages when opening pipes from docker_wsl on Windows. Removing it reverts to the default settings that work from both Windows and WSL 2.

If you don't see the WSL Integration section in Docker Desktop, you may be in mode Windows containersSwitch to Linux containers from the system tray icon. Then return to Settings to enable the integration.

Remember that WSL exposes the file system to the host in \\wsl$\This isn't unique to Docker Desktop; it's part of the WSL interoperability model. Docker Desktop, for its part, runs on its own internal distribution. docker-desktop, with the same isolation as any other WSL distribution; it only interacts with others when you activate WSL integration.

If you're looking to harden the environment for security reasons, consider using Hyper-V or advanced container isolation policies. For general development, WSL 2 is sufficient, but some organizations prefer extra protection depending on their risk level.

With all of the above, you now have a complete picture to choose how to work: use Docker Desktop with the WSL 2 engine for a guided and stable experience, or install Docker directly on WSL 2 to reduce external dependencies; if you also combine VS Code, its extensions, and host the projects within the WSL file system, you'll enjoy an agile and consistent environment, with fine performance controls, clear data paths and immediate solutions to common mistakes.