Configuring Docker Desktop and WSL2 for development on Windows 11

Working with Docker containers on Windows 11 is no longer just for system gurus: thanks to Docker Desktop and WSL2, it's possible to set up a powerful, lightweight development environment that closely resembles native Linux without leaving your Windows machine. With the right combination of configuration, tools, and best practices, you can compile, debug, and deploy containerized applications to both Linux and Windows from the same machine, making the most of your hardware.

The goal of this guide is to help you get everything running smoothly : installing and configuring WSL2, setting up Docker Desktop using the WSL2 engine, integrating VS Code, configuring Git, databases, and remote development containers, and even fine-tuning performance, security, and troubleshooting common issues (proxy, slow paths, storage , etc.). Everything is explained step-by-step, in Spanish (Spain), and with a very practical approach.

Key concepts: Docker containers, WSL2, and Docker Desktop

Before you start installing things willy-nilly , it's worth understanding what each component contributes. Docker is a platform that allows you to package applications along with all their dependencies (libraries, frameworks, binaries, configuration, etc.) into lightweight units called containers. These containers are based on images and guarantee that the application will run the same on any machine, without you having to struggle with "it works on my machine."

Unlike a traditional virtual machine , a container doesn't boot a complete operating system. Instead, it shares the host kernel (in this case, Linux) and isolates processes using namespaces and cgroups. The result is smaller packages, near-instant startups, and much more efficient resource usage, which is especially noticeable when working with many microservices or CI/CD pipelines.

WSL2 (Windows Subsystem for Linux 2) is the second generation of Microsoft's Linux subsystem and adds a real Linux kernel running in a lightweight virtual machine. This represents a huge leap forward compared to WSL1: improved disk and network performance, greater compatibility with native Linux tools, and, most importantly for our purposes, full support for Linux-based Docker containers.

Docker Desktop for Windows acts as the glue that holds everything together: it provides a graphical interface for managing containers, images, volumes, and networks, exposes a fully Docker-compliant CLI, and, when you enable the WSL2-based engine, lets you run Linux and Windows containers on the same machine using the Linux kernel running inside WSL2.

Prerequisites and system preparation

For Docker Desktop and WSL2 to work properly on Windows 11, you need to meet certain hardware and software requirements. It's important to review these to avoid unusual errors during installation or when starting the Docker daemon.

At the operating system levelIt is recommended to use Windows 11 or a recent version of Windows 10 with WSL2 support (build 20262 or higher). You can check the version by pressing Windows + R and typing winver and checking the installed build. In Windows 11, the simplified command wsl --install It is available and makes the initial setup much easier.

In the virtualization section , ensure that hardware virtualization support ( Intel VT-x, AMD-V) is enabled in the BIOS/UEFI. Windows will use the "Virtual Machine Platform" feature, which is essential for WSL2 and the Docker backend when not using traditional Hyper-V. If you plan to use the alternative backend with Hyper-V, you will also need a Pro, Enterprise, or equivalent edition.

It's also advisable to review the official Docker Desktop requirements (64-bit CPU, at least 4 GB of RAM, administrator privileges, and sufficient disk space for images and containers). For specific installations on Windows Server, there are separate guides, but this article will focus on desktop environments with Windows 11.

Installing and configuring WSL2 on Windows 11

The first serious step to getting Docker running smoothly on Windows 11 is to ensure WSL2 is properly installed and configured. Without a well-configured WSL2, the Docker backend for Linux will not run smoothly or may not even start.

In Windows 11, the quick way is to use PowerShell as administrator and run the command:

wsl --install

This command automates several critical tasks : it enables the optional features "Windows Subsystem for Linux" and "Virtual Machine Platform", downloads and installs the latest Linux kernel, sets WSL2 as the default version, and automatically adds an Ubuntu distribution (if all goes well, with an intermediate reboot).

If you want a different distribution or are installing on Windows 10 , you can manually enable the features from "Turn Windows features on or off" or via PowerShell, and then install your preferred distribution (Ubuntu, Debian, Fedora, etc.) from the Microsoft Store. Later, you can force it to use WSL2 with:

wsl --set-default-version 2

Once the distribution is installed for the first timeWhen you open it from the Start menu, you'll be prompted to create a Linux username and password. These are not linked to your Windows user account, and when you type the password, you won't see any characters on the screen (this is normal in the terminal). This user will have administrator privileges within the distribution and will be able to run commands. commands with sudo.

If in some moment Forgot your password? of the distroYou can log in with the username root from PowerShell running wsl -u root (o wsl -d <Distro> -u root (if it is not the default) and change the password with passwd <usuario>After updating it, you exit with exit and ready.

It is highly recommended to update the packages immediately after installation , especially if you are going to use the distro as a development environment. In Ubuntu or Debian, from the Linux terminal itself:

sudo apt update && sudo apt upgrade

Docker Desktop installation with WSL2 backend

With WSL2 up and running, you can now move on to Docker Desktop . The idea is to install Docker using the WSL2 engine instead of relying on Hyper-V, which typically offers better performance, lower resource consumption, and a much more seamless integration with Linux tools.

Download the Docker Desktop installer from the official Docker website, making sure to select the Windows version. The installer is the same for multiple platforms, so check that you have the correct executable for your system, not the Linux or macOS version.

When you launch the Docker Desktop installer , you'll see a fairly simple wizard. Select the option to "Use WSL2-based engine" (or similar, depending on the version) so that Docker uses the WSL2 backend instead of Hyper-V. You can also create a desktop shortcut for easy access.

The installation process takes a few minutes , depending on your machine, as it copies binaries, services, and configures integrations. Once it's finished, you'll be prompted to restart your system. After the second restart , open Docker Desktop from the Start menu or using the desktop icon and accept the license terms (it's free for personal and small business use).

If you haven't already completed WSL2 , Docker will prompt you to download and install the WSL2 kernel. Follow the link provided by the program, install the kernel package, restart, and when you reopen Docker Desktop, the WSL2 backend should be ready.

Verification and basic settings of Docker Desktop with WSL2

With Docker Desktop launched, it's time to fine-tune and verify that everything is working correctly . From the Docker icon in the system tray (hidden icons), right-click and go to "Settings".

In the General section , verify that the option equivalent to “Use the WSL 2 based engine” is enabled. This ensures that Linux containers run on the WSL2 kernel and does not create an additional virtual machine with Hyper-V, thus saving memory and CPU resources.

Next, go to Resources > WSL Integration . Here you'll see a list of available WSL distributions (Ubuntu, Debian, etc.) and can choose which ones to enable Docker integration on. Activate your main distribution (for example, Ubuntu ) so you can run Docker commands directly from that distribution.

To confirm that the Docker CLI is responding , open a WSL terminal (Ubuntu, for example) and run:

docker --version

If the command returns the Docker client and server versions , the environment is ready. As further proof, you can launch the typical "hello-world" test image with:

docker run hello-world

If you see the Docker welcome message within the Linux terminal , it means that Docker Desktop is responding through the WSL2 backend and is able to download images from the official registry and run them successfully.

Performance: Why using WSL2 and the correct file path is key

One of the most frequent mistakes that causes Docker to run slowly on Windows is incorrectly mixing WSL1, WSL2, and file paths. A poorly configured environment can drastically increase compilation times and disk access within containers.

To take full advantage of Docker Desktop's performance on Windows 11Make sure you're using WSL2 (not WSL1) for the distribution that integrates Docker, and above all, store your source code within the WSL filesystem and not on a Windows drive mounted in /mnt/c or similar.

The practical recommendation is simple.In your WSL distro terminal, locate your projects under your directory. /home/<usuario>, for example /home/miusuario/proyectosIf you want to view those files from Windows, you can open the file explorer with:

explorer.exe .

Behind this lies a clear performance motive.When containers access files located in the internal WSL2 file system, I/O is much faster than when traffic is handled using paths like C:\ mounted under /mnt/cFor large projects (Node, Python, Java, etc.) the difference between the two approaches is very noticeable.

WSL distribution management and Docker storage

If you're going to work seriously with WSL2 , you'll probably end up using more than one distribution (Ubuntu for development, another for testing, etc.). You can list your installed distributions and their WSL version with:

wsl -l -v

If any of them are still using WSL1 , you can migrate them to WSL2 with:

wsl --set-version NombreDistro 2

Regarding Docker storage within WSLDocker Desktop creates two special distributions for its own data: docker-desktop y docker-desktop-dataThese are also presented as network routes:

• \\wsl$\docker-desktop
• \\wsl$\docker-desktop-data

If you need to locate those folders from WindowsYou can open your WSL distro and run explorer.exe . and then navigate to \\wsl\<Distro>\mnt\wsl (replacing by the actual name, for example Ubuntu-24.04) to see where that data resides.

It's important to be aware of where images and volumes are stored , because they take up disk space, and if you use WSL2 extensively, the VM file size can grow considerably. It's always a good idea to periodically review images and containers that you no longer need.

Integration with VS Code: containerized development and debugging

One of the most powerful combinations with Docker and WSL2 is using Visual Studio Code as your primary development environment. VS Code directly supports remote work in WSL and development containers, allowing you to edit, compile, and debug within an isolated Linux environment without leaving Windows.

To set up this workflow , install VS Code on Windows and then add three key extensions:

• Remote – WSL: allows you to open folders located in your WSL distro directly in VS Code.
• Dev Containers (formerly Remote – Containers): allows you to open a project folder within a development container defined by Dockerfile y devcontainer.json.
• Docker: adds panels and commands to manage images, containers, volumes, and logs from VS Code.

A typical workflow would look something like this : First, from your WSL terminal, you clone a repository of your project (for example, a sample Django) with:

git clone https://github.com/<usuario>/helloworld-django.git

Then you enter the project folder with cd helloworld-django and open VS Code pointing to that route with:

code .

If the WSL extension is active, you will see it in the bottom bar. The green indicator shows that you are connected to the Linux distro, not the Windows session. From there, you can use the Command Palette (Ctrl + Shift + P) and run “Dev Containers: Reopen in Container” if you are already in a WSL folder, or “Dev Containers: Open Folder in Container…” to choose another folder (even through the resource \\wsl$).

When selecting a default container configuration (for example, “Python 3” for Django projects), VS Code will generate the folder .devcontainer with a Dockerfile or with a devcontainer.jsonVS Code will start a development container, rebuild the image if necessary, and open a new window connected to that container.

Inside the container, the integrated VS Code terminal It will show that you are on Linux (you can check it with unameThe Python version will be determined by the container image, not by the one installed on your WSL distribution. This allows you to have repeatable and isolated development environments for each project.

To debug your application from VS CodeGo to the “Run and Debug” tab, choose the appropriate configuration (for example, “Django”), and VS Code will create a launch.json with the startup parameters. Pressing F5 will start the development server inside the container and you can open your application in the browser (for example, in http://127.0.0.1:8000/).

Basic use of Docker in Windows 11

Once Docker Desktop is up and running , you can use standard Docker commands from both PowerShell and WSL to manage images and containers. This will allow you to go beyond basic testing and deploy real services.

The most commonly used commands at the beginning are usually:

• docker: displays the list of available commands.
• docker <comando> --help: brief documentation of each command.
• docker image ls --all: list of all images stored on your system.
• docker container ls --all o docker ps -a: shows all containers, running or stopped.
• docker info: global information about the Docker installation (backend, memory, number of containers, etc.).

From the Docker Desktop graphical interface, you can also search for images on Docker Hub, "pull" to download them, start new containers, check CPU/RAM usage, or inspect logs . It's a convenient way to get started if you're not yet entirely comfortable with the command line.

It's important to remember that not all images are equally reliable or secure . Docker Desktop includes vulnerability scans for some images, but in general, it's good practice to use official or well-maintained images, check the tags, and avoid outdated images with obsolete components.

WSL2 and container best practices for development

For a stable and comfortable development environment over time , it is not enough for it to "start up"; it is advisable to follow a series of good practices in both WSL2 and Docker Desktop.

In WSL2, keep the kernel and distributions updated. using wsl --update From Windows and the package manager (apt, dnf, etc.) within each distribution. Use non-root users for daily work, reserve root for specific administrative tasks, and control resource consumption if you run heavy loads (you can limit WSL2 memory and CPU with configuration files).

When developing with containers , try to keep your code and tools on the same "side" (Linux or Windows) to avoid I/O bottlenecks caused by using cross-filesystems. If you're compiling within containers, place your projects on the WSL2 filesystem and access them from Docker using direct volumes.

For corporate or production environments , it's essential to complement Docker with orchestration tools like Kubernetes and implement additional security policies (image scanning, access control to private logs, credential rotation, etc.). Specialized companies can help you design development and deployment architectures, integrating WSL2, Docker, CI/CD, and cloud services (Azure, AWS) with appropriate cybersecurity measures.

In terms of security within WSL2 , even though it runs in a lightweight VM, you still need to apply security patches, use firewalls, and protect both the Windows host and the Linux distributions. Also, ensure that containerized applications do not expose unnecessary ports or services to the outside of your network.

Interoperability between Windows and Linux in WSL

One of WSL2's strengths is the seamless integration between Windows and Linux commands . You can combine tools from both worlds in the same pipeline, which is very useful for scripting and automation.

From a Windows terminal (PowerShell or CMD)You can launch Linux commands through wslFor example, to list the contents of C:\temp using ls -la from Linux:

wsl ls -la

You can also combine filters from both sides , for example:

wsl ls -la | findstr "git"

Or vice versa, using Windows commands from WSL adding .exeFor example, to edit the file .bashrc from your user account using Windows Notepad:

notepad.exe .bashrc

This interoperability facilitates tasks such as filter the output of ipconfig.exe with grepOpen graphic editors from Linux, or work with files from both systems without having to constantly switch windows.

Git, database, and GPU configuration in WSL2

Beyond Docker, a modern development environment with WSL2 typically includes version control with Git, databases, and in some cases, GPU acceleration for machine learning or computationally intensive tasks.

For Git, the recommendation is to work within WSL2 using the Linux Git CLI, connecting to GitHub, GitLab, or similar services via SSH keys or credential managers. VS Code integrates very well with Git and allows you to manage branches, commits, and conflicts visually.

Regarding databases , you can install and manage engines like MySQL, PostgreSQL, MongoDB, Redis, or SQLite in WSL2, and connect your containers to them or vice versa. Specific guides exist for running each of these databases in WSL2, taking advantage of their near-native performance.

If you work with AI or high-performance computing , WSL2 supports GPU acceleration on Windows 11 with the appropriate drivers . This allows you to run frameworks like TensorFlow or PyTorch on Linux, within WSL2 or even in Docker containers, directly using your computer's graphics card.

This entire ecosystem can be integrated with CI/CD pipelines and cloud services , so that what you develop and test on your Windows laptop with WSL2 and Docker looks very similar to the environment you will later deploy in production (in containers, Kubernetes, or managed services).

Troubleshooting common problems with Docker Desktop and WSL2

No matter how well you set it up, problems will inevitably arise . Knowing the common errors and how to resolve them saves you a lot of headaches, especially in corporate environments with network constraints.

A classic example is the legacy Docker “wsl” context from older technical versions of Docker for WSL. If you run docker context ls and you see a context called wslIt is likely already obsolete and will cause errors such as “open //./pipe/docker_wsl: the system cannot find the file specified”.

The solution involves deleting that old context with:

docker context rm wsl

After removing it, Docker will use the default context for both Windows and WSL2, avoiding those connection errors to the Docker daemon through pipes that no longer exist.

Another very common problem is working behind a corporate proxy. which requires authentication with usuario:contraseñaDocker Desktop often throws errors when including credentials in environment variables. HTTP_PROXY or in the program's direct configuration, displaying messages such as "invalid http proxy in user configuration: must not include credentials".

In these cases, there are several somewhat safer optionsUse an external authenticator proxy (such as CNTLM) that manages credentials and exposes a local proxy without a username/password, configure the proxy in Windows and Docker without embedding credentials in the URL, or use dedicated credential stores. Manually edited settings.json o config.json Forcing a username:password in the URL in Docker Desktop often causes Docker to fail to start or ignore that setting.

If the problem is with the WSL2 installation (errors while executing) wsl --install or when starting the distro), it is advisable to review the WSL troubleshooting guide: check that the Windows features are properly enabled, that the WSL2 kernel has been installed correctly and that the system is up to date with the latest patches.

For other more specific problems (Docker storage paths, mounting external disks, running Linux GUI applications, etc.), the official WSL documentation and its repository issues contain example commands such as wsl --mount and specific configurations for each case.

With everything you've seen, you have a very solid foundation for setting up a modern development environment on Windows 11 supported by WSL2, Docker Desktop, and VS Code: you'll be able to work with Linux containers almost as if you were on a native distribution, integrate Git and databases, use GPU acceleration when you need it, and above all, do it with performance and flexibility far superior to traditional virtualization, while maintaining a good level of security and control over your resources.