Configuring Docker Desktop and WSL2 for development on Windows 11

Working with Docker containers on Windows 11 It's no longer something reserved 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 Linux and Windows applications from the same machine, making the most of your hardware.

The aim of this guide is to help you get everything just right.Install and configure WSL2, launch Docker Desktop using the WSL2 engine, integrate VS Code, configure Git, databases and remote development containers, and even fine-tune performance, security and troubleshoot typical problems (proxy, slow routes, storageetc.). Everything is explained step by step, in Spanish from Spain, and with a very practical approach.

Key concepts: Docker containers, WSL2, and Docker Desktop

Before you start installing things willy-nillyIt'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 classic virtual machineA 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) It's 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 from WSL1: improved disk and network performance, greater compatibility with native Linux tools, and, most importantly for us here, full support for Linux-based Docker containers.

Docker Desktop for Windows acts as the glue It brings everything together: it provides a graphical interface for managing containers, images, volumes, and networks, exposes a fully Docker-compatible CLI, and, when you enable the WSL2-based engine, allows you to 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 a number of hardware and software requirements. It's important to review them 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, make sure that hardware virtualization support (Intel VT-x, AMD-V) must be enabled in the BIOS/UEFI. Windows will use the "Virtual Machine Platform" feature, which is essential for WSL2 and the Docker backend when traditional Hyper-V is not used. If you plan to use the alternative backend with Hyper-V, you will also need a Pro, Enterprise, or equivalent edition.

It's also a good idea to review the official Docker Desktop requirements. (64-bit CPU, minimum 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 in this article, we will focus on desktop environments with Windows 11.

Installing and configuring WSL2 on Windows 11

The first serious step towards having a fine-tuned Docker on Windows 11 It's essential to ensure WSL2 is properly installed and configured. Without a correctly set up 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 execute the command:

wsl --install

This command automates several critical tasks: 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 distro or you're installing on Windows 10You 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 to 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're 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 DesktopThe idea is to install Docker using the WSL2 engine instead of relying on Hyper-V, which usually offers better performance, lower resource consumption, and a much more natural integration with Linux tools.

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

When launching the Docker Desktop installerYou'll have a fairly simple wizard. Select the option to "Use the WSL 2-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 easier access.

The installation process takes a few minutesDepending on the machine, this may take some time, as binaries and services are copied and integrations are configured. Once finished, it will ask you to restart the system. After the second BootOpen 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 didn't already have WSL2 properly completedDocker will display a prompt 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 adjust and check that everything is working correctly.From the Docker icon in the system tray (hidden icons), right-click and enter “Settings”.

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

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

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

docker --version

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

docker run hello-world

If you see the Docker welcome message inside the Linux terminalThis 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 errors that makes Docker run slowly on Windows It's due to incorrectly mixing WSL1, WSL2, and file paths. A poorly configured environment can significantly 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 WSL2You'll likely 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 WSL1You can migrate it 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 is 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 It involves using Visual Studio Code as your primary development environment. VS Code directly supports remote work in WSL and development containers, so you can edit, compile, and debug within an isolated Linux environment without leaving Windows.

To set up this workflowInstall 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 flow would look something like thisFirst, from your WSL terminal, 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 to 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 runningFrom both PowerShell and WSL, you can use standard Docker commands 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 they 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 logsIt's a convenient way to start if you're not yet completely comfortable with the command line.

It's worth remembering that not all images are equally reliable or secure.Docker Desktop includes vulnerability scanning for some images, but in general it's good practice to rely on 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 in ThereIt is not enough for it to "start", 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).

Under development with containersTry 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 in the WSL2 filesystem and access them from Docker using direct volumes.

For corporate or production environmentsIt is essential to complement Docker with orchestration tools such as Kubernetes and apply 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 the appropriate security measures. ciberseguridad.

In terms of security within WSL2Even 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, make sure that the containerized applications don't expose unnecessary ports or services to the outside of your network.

Interoperability between Windows and Linux in WSL

One of the strengths of WSL2 is the good compatibility between Windows and Linux commands.You can mix tools from both worlds in the same pipeline, which is very useful for scripts and automations.

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 to 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 It usually 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 seamlessly with Git and allows for visual management of branches, commits, and conflicts.

Regarding databasesYou can install and manage database 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 computingWSL2 supports GPU acceleration on Windows 11 with the drivers suitable. This allows you to run frameworks like TensorFlow or PyTorch on Linux, within WSL2 or even in Docker containers, directly using the computer's graphics card.

This entire ecosystem can be integrated with CI/CD pipelines and cloud servicesso that what you develop and test on your Windows laptop with WSL2 and Docker is 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 appear sooner or laterKnowing the typical failures and how to solve them saves you a lot of headaches, especially in corporate environments with network restrictions.

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 Docker daemon connection errors 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. Powered by WSL2, Docker Desktop, and VS Code, you can 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 so with performance and flexibility far superior to traditional virtualization, while maintaining a good level of security and control over your resources.