18.1.1.1 Desktop Windows Integration

Desktop Windows integration covers the specific points where Docker Desktop connects with Windows-native concepts, WSL2 distro access, the Linux-versus-Windows containers toggle, path translation between the two filesystems, and common friction points like antivirus interaction and line-ending differences, each of which is a Windows-specific consideration distinct from the underlying backend choice itself.

WSL2 distro integration settings

When using the WSL2 backend, Docker Desktop's integration with specific WSL2 distributions is configured explicitly, determining which installed Linux distributions actually have the docker command available within them:

Settings > Resources > WSL Integration > Enable integration with additional distros

wsl -l -v

A distro not explicitly enabled in this integration list will not have Docker CLI access at all, even though Docker Desktop itself is running and otherwise functional, which is a common point of confusion for anyone working across multiple WSL2 distributions who has not enabled integration for the specific one they are currently using.

Linux containers versus Windows containers

Docker Desktop on Windows supports switching between running Linux containers (the overwhelmingly more common case, using the virtualized Linux environment) and genuine Windows containers (running directly on the Windows kernel, with no Linux virtualization layer involved at all), and these two modes are mutually exclusive at any given moment, not something a single Docker Desktop instance runs simultaneously:

Right-click Docker Desktop tray icon > Switch to Windows containers...

docker info --format '{{.OSType}}'

Confirming which mode is currently active directly is worth doing explicitly whenever an image or command unexpectedly fails to behave as expected, since an attempt to run a Linux-based image while in Windows containers mode (or vice versa) produces a clear architecture mismatch failure that is otherwise easy to misdiagnose as an unrelated problem.

Path translation between Windows and WSL filesystems

A bind mount or file reference using a native Windows path needs to be expressed correctly for whichever context Docker actually interprets it from, and confusion between a Windows-style path and its WSL2 equivalent is a frequent source of an unexpectedly empty or incorrect bind mount:

docker run -v C:\Users\dev\project:/app my-api

docker run -v /mnt/c/Users/dev/project:/app my-api

docker run -v ~/project:/app my-api

Running Docker commands from within a WSL2 terminal session, working with project files that live within the WSL2 filesystem itself rather than on the Windows-mounted /mnt/c/ path, generally produces both better performance and fewer of these path-translation points of confusion than working across the Windows-to-WSL2 boundary repeatedly.

PowerShell versus WSL terminal considerations

Running Docker commands from a native PowerShell session versus from within a WSL2 terminal session can behave subtly differently, particularly around path syntax and certain shell-specific quoting and escaping rules, and being explicit about which terminal context a given command or script is actually written for avoids confusion when the identical-looking command behaves differently depending on where it is actually run:

docker run -v ${PWD}:/app my-api

docker run -v "$(pwd)":/app my-api

Documenting which shell context a given project's scripts and instructions assume, rather than leaving it ambiguous, helps anyone following those instructions know which terminal to actually use.

Antivirus and Windows Defender interaction

Windows's own antivirus scanning, including the built-in Windows Defender, can meaningfully degrade Docker Desktop's file-sharing and build performance, particularly for bind-mounted directories containing many small files, since each file access can trigger a real-time scan unless explicitly excluded:

Windows Security > Virus & threat protection > Exclusions > Add an exclusion

Adding an exclusion for the WSL2 virtual disk file and any frequently bind-mounted project directories is a common, meaningful performance improvement specifically relevant on Windows, with no equivalent concern on a native Linux Docker installation.

Line ending differences affecting builds

Windows's default line ending convention (CRLF) differs from the LF convention Linux-based tooling and shell scripts generally expect, which can cause a script copied into a Linux-based image to fail with a confusing error if it was checked out or edited with Windows-style line endings:

/entrypoint.sh: line 1: $'\r': command not found

*.sh text eol=lf

A .gitattributes entry enforcing LF line endings specifically for shell scripts, regardless of which platform checks the repository out, prevents this specific, Windows-originated line-ending issue from ever reaching a Linux-based container build at all.

Common mistakes

• Not enabling WSL integration for the specific distro being used, leaving the docker command unavailable within it despite Docker Desktop running correctly.
• Confusing Linux containers mode with Windows containers mode, attempting to run an image built for one while Docker Desktop is actually configured for the other.
• Repeatedly crossing the Windows-to-WSL2 path boundary for bind mounts rather than keeping project files within the WSL2 filesystem directly for better performance and less path-translation confusion.
• Not excluding Docker Desktop's WSL2 virtual disk and bind-mounted project directories from Windows Defender's real-time scanning, leaving meaningful, avoidable performance overhead in place.
• Not enforcing consistent line endings for shell scripts through .gitattributes, risking a Windows-checkout-introduced CRLF issue breaking a script once it runs inside a Linux-based container.

Desktop Windows integration involves several Windows-specific considerations, distro integration settings, the Linux-versus-Windows containers mode toggle, path translation, antivirus interaction, and line-ending consistency, each distinct from the underlying virtualization backend choice itself and each worth understanding explicitly to avoid friction unique to running Docker Desktop specifically on Windows.