> ## Documentation Index
> Fetch the complete documentation index at: https://felimet-hub.jmcores.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Performance Settings (WSL 2 backend and the daemon)

> How the WSL 2 backend allocates CPU and memory (.wslconfig), WSL integration commands, where Docker data lives, and daemon.json.

`Docker` `WSL 2` `Configuration`

This is the easiest thing to get wrong on Windows: **under the WSL 2 backend, Docker's CPU and memory are not set in the Docker Desktop GUI**; they are controlled by the WSL 2 utility VM's config file.

## Connecting to the WSL 2 backend

1. Docker Desktop → Settings → General → check **Use the WSL 2 based engine**.
2. Settings → Resources → **WSL Integration** → enable the distros where you want `docker` available (such as Ubuntu) → Apply & Restart.

With integration on, you can use `docker` directly from that distro's Linux terminal.

<Note>
  Only the **Hyper-V backend** (or macOS / Linux) sets CPU / memory / swap directly under Docker Desktop's Settings → Resources → Advanced. The WSL 2 backend uses `.wslconfig` below.
</Note>

## Allocating resources (`.wslconfig`)

CPU / memory / swap are set in the `[wsl2]` section of `%UserProfile%\.wslconfig` (create the file if missing). **The `[wsl2]` section header is mandatory**, or the settings are ignored:

```ini theme={null}
# Path: C:\Users\<your-username>\.wslconfig
[wsl2]
memory=8GB       # WSL 2 VM memory cap (default is 50% of physical RAM)
processors=4     # virtual processors available (default equals logical processor count)
swap=8GB         # swap size (0 to disable)
# swapfile=C:\\WSL\\wsl-swap.vhdx   # swap file location (default %Temp%\swap.vhdx)

[experimental]
autoMemoryReclaim=dropCache   # automatically release idle memory
sparseVhd=true                # auto-sparsify new VHDs to save real disk usage
```

Restart WSL to apply:

```powershell theme={null}
wsl --shutdown          # shut down all WSL distros (about 8s to fully stop)
wsl --list --running    # confirm none are still running
wsl -d Ubuntu           # start again, settings now applied
```

## Common WSL integration commands

```powershell theme={null}
wsl -l -v                       # list distros, WSL version (1 or 2), and state
wsl --set-default-version 2     # new distros default to WSL 2
wsl --set-version Ubuntu 2      # convert an existing distro to WSL 2
wsl --update                    # update the WSL kernel
wsl --shutdown                  # shut down all WSL (required to apply .wslconfig)
wsl --terminate Ubuntu          # shut down only one distro, leaving others running
wsl --status                    # WSL version and kernel info
```

## Where Docker data lives and how to check its size

Under the WSL 2 backend, Docker's image layers, containers, and volume data all live in the virtual disk (VHDX) of the **`docker-desktop-data`** WSL distro, by default at:

```
C:\Users\<UserName>\AppData\Local\Docker\wsl\
```

```powershell theme={null}
wsl -l -v        # you will see both docker-desktop and docker-desktop-data
```

```
  NAME                   STATE       VERSION
* Ubuntu                 Running     2
  docker-desktop         Stopped     2
  docker-desktop-data    Stopped     2
```

The `docker-desktop-data` VHDX is the source of disk usage. It **grows dynamically but does not shrink back automatically**, and File Explorer does not show its real usage; check with a command:

```powershell theme={null}
Get-ChildItem "$env:LOCALAPPDATA\Docker\wsl" -Recurse -File |
  Select-Object Name, @{N='Size(MB)';E={[math]::Round($_.Length/1MB,1)}}
```

Reclaim space via the [cleanup commands](/en/notes/docker/guide/cli/) (`docker system prune`). To move the VHDX: Docker Desktop → Settings → Resources → Advanced → **Disk image location**.

## daemon.json (Docker engine settings)

To tune registry mirrors, log rotation, default runtime, and other engine-level settings, edit the daemon config. **On Docker Desktop you do not edit the file directly**; use the JSON editor under Settings → Docker Engine. Only native Linux installs use `/etc/docker/daemon.json`.

```json theme={null}
{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" },
  "registry-mirrors": ["https://mirror.example.com"],
  "default-runtime": "runc",
  "live-restore": true
}
```

Common keys: `log-opts` caps per-container log size and file count (worth adding by default so logs do not fill the disk), `registry-mirrors` speeds up pulls, `data-root` changes the data root, `live-restore` keeps containers running across a daemon restart.

## Next

* [Where data lives](/en/notes/docker/guide/storage/): volume vs bind mount performance on WSL 2.
* [Docker CLI commands](/en/notes/docker/guide/cli/): cleanup commands to reclaim VHDX space.

Reference: [docs.docker.com/desktop/features/wsl](https://docs.docker.com/desktop/features/wsl/), [learn.microsoft.com/windows/wsl/wsl-config](https://learn.microsoft.com/windows/wsl/wsl-config)