Solving WSL 2 Docker File Permission Issues

TLDR

• Core Issue: In a WSL 2 environment, files created by Docker containers with root privileges cause VS Code (running as a standard user) to encounter Permission Denied errors when attempting to read or write them.
• Brute-force Solution (Not Recommended): Modifying /etc/wsl.conf to set the default WSL user to root. While this resolves permission issues, it poses significant security risks.
• Recommended Approach (Dev Containers): Use the VS Code Dev Containers feature to containerize the development environment and resolve Bind Mount permission conflicts via the "remoteUser": "root" setting.
• Advanced Approach (Integration with Docker Compose): Define a vscode-editor service in compose.yml and connect via Dev Containers: Attach to Running Container to integrate the development environment with project infrastructure.
• Key Tip: When using docker-outside-of-docker with Bind Mounts, path resolution points to the Host. It is recommended to prioritize using Named Volumes to avoid path mapping issues.

---

The Permission Hell Encountered

When does this issue occur? When you start a Docker container in WSL 2 and mount files (Volume) to a local directory.

Since Docker containers run with root privileges by default, the owner of files mounted to WSL becomes root. When you attempt to edit these files using VS Code running as a standard user, the operation fails due to insufficient permissions.

Brute-force Solution

Directly modify the WSL configuration file /etc/wsl.conf to change the default login user to root.

# /etc/wsl.conf
[user]
default = root

WARNING

This is an extremely insecure practice. Changing the default user to root grants you administrative privileges for all operations within WSL. If you accidentally execute a malicious script or make an operational error (e.g., rm -rf /), the consequences could be catastrophic. Please do not replicate this in production or critical work environments.

---

Solution: Dev Containers

When does this issue occur? When you want to maintain environment consistency while resolving cross-OS file access permission issues.

Dev Containers allow you to package the development environment within a container and resolve permission conflicts by automatically syncing the UID or specifying a remoteUser.

Dev Containers Practical Steps

1. Initialization: Press F1 in VS Code and select Dev Containers: Add Dev Container Configuration Files....
2. Select Definition: Choose a suitable environment (e.g., Ubuntu) and ensure you check the Docker (outside of Docker) feature.
3. Configure devcontainer.json: If using Bind Mount, you must enable remoteUser in the configuration file:

   "remoteUser": "root"

4. Reopen: Press F1 and select Dev Containers: Reopen in Container.

TIP

If devcontainer.json is modified, you must perform a Rebuild for changes to take effect. If you miss the rebuild prompt, you can re-run it via the command palette.

---

Advanced Approach: Integrating Dev Container into Docker Compose

When does this issue occur? When you do not want to create an extra .devcontainer folder, or you prefer to define the development environment and project services in the same compose.yml.

You can add a dedicated container service for editing:

Configuration Method

Add the following to compose.yml or compose.override.yml:

services:
  vscode-editor:
    image: mcr.microsoft.com/devcontainers/base:ubuntu-24.04
    container_name: vscode-editor
    command: sleep infinity
    user: root
    volumes:
      - ./:/workspace
    working_dir: /workspace

Connection Steps

1. Start the service: docker compose up -d.
2. Press F1 in VS Code and select Dev Containers: Attach to Running Container....
3. Select the vscode-editor container.
4. Open the /workspace directory inside the container.

TIP

If you do not want development environment settings to pollute your production compose.yml, it is recommended to move the above configuration to compose.override.yml. Docker Compose will automatically merge the configurations.

---

Change Log

• 2026-01-19 Initial document creation.
• 2026-01-22 Added another method for integrating Dev Container into Docker Compose.
• 2026-02-04 Added recommendations regarding the use of compose.override.yml.