microsoft / microsoft/WSL

[Feature Request] Support registry mirror configuration in WSLC settings.yaml

Open
#40,951 2 comments 7 reactions 1 assignee View on GitHub

@craigloewen-msft is already working on this.

Since Jul 7, 2026.

feature wslc
Dominant language
C++
Stars
33.7k
Forks
1.8k
Avg merge
3d 17h
Merged PRs (30d)
116

Description

## Description

WSLC (WSL Container) currently does not support configuring registry mirrors in `settings.yaml`. When users in regions with restricted access to Docker Hub (e.g., China) try to pull images using `wslc pull`, the request times out with:

```
Get "https://registry-1.docker.io/v2/": context deadline exceeded
```

Unlike Docker, which supports `registry-mirrors` in `daemon.json`, WSLC has no equivalent configuration option.

## Current Workaround

Users can work around this by using the full mirror address directly:

```powershell
wslc pull docker.m.daocloud.io/library/alpine:latest
```

Or by exporting from Docker and importing to WSLC:

```powershell
docker save alpine:latest -o alpine.tar
wslc load -i alpine.tar
```

## Proposed Solution

Add a `registryMirrors` (or similar) configuration option to `settings.yaml`, similar to Docker's `daemon.json`:

```yaml
session:
cpuCount: default
memorySize: default

# New: Registry mirror configuration
registry:
mirrors:
- docker.m.daocloud.io
- docker.1panel.live
```

This would allow WSLC to automatically redirect image pull requests to the configured mirrors.

## Source Code Analysis

After reviewing the source code:

- `src/windows/common/WSLCUserSettings.h` defines only 9 settings (none related to registry mirrors)
- `src/windows/wslc/services/ImageService.cpp` calls `PullImage()` directly without any mirror redirect logic
- `src/windows/WslcSDK/wslcsdk.h` defines `WslcPullImageOptions` without a mirror field

## Environment

- WSLC version: Latest (Preview)
- Windows version: Windows 11
- Region: China (Docker Hub inaccessible)

## Additional Context

This is a common requirement for users in regions with network restrictions. Docker, Podman, and containerd all support registry mirror configuration. Adding this feature to WSLC would significantly improve the user experience for international users.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.