How to fix Error response from daemon: user namespace remapping is not supported in Docker

DockerADVANCEDMEDIUMUpdated Dec 6, 2025· 236 views

This error occurs when Docker's user namespace remapping feature (userns-remap) is enabled but the host kernel doesn't support user namespaces, or required configuration files are missing. The fix involves enabling kernel support for user namespaces and properly configuring the /etc/subuid and /etc/subgid files.

Quick fix

Fixes Error response from daemon: user namespace remapping is not supported

cat /proc/sys/user/max_user_namespaces
  1. Check if user namespaces are enabled in the kernel
  2. Enable user namespaces on CentOS/RHEL 7
  3. Enable user namespaces on modern systems (Ubuntu/Debian/Fedora)
  4. Create the subuid and subgid files
docker — error
cat /proc/sys/user/max_user_namespaces
Error response from daemon: user namespace remapping is not supported

What this error means

User namespace remapping is an advanced Docker security feature that isolates container root users from the host's root user. When enabled, container processes running as root (UID 0) are mapped to an unprivileged high-numbered UID on the host, preventing privilege escalation attacks. This error appears because: - The Linux kernel on your host does not have user namespace support enabled - The required configuration files (`/etc/subuid` and `/etc/subgid`) are missing or misconfigured - The Docker daemon is configured to use userns-remap, but the system cannot support it - On older systems like CentOS 7 or RHEL 7, user namespaces are disabled by default in the kernel The Docker daemon checks for user namespace support at startup. If you've added `"userns-remap": "default"` or similar to your `/etc/docker/daemon.json`, Docker will fail to start containers if the host cannot provide this isolation mechanism.

Typical symptoms

  • Docker daemon fails to start after enabling userns-remap in daemon.json
  • Containers fail to start with 'user namespace remapping is not supported' error
  • Docker info shows userns-remap is configured but containers won't run
  • docker run commands fail immediately after configuring user namespace remapping
  • Error appears after upgrading Docker or changing security configurations

Common causes

  1. User namespaces are disabled in the Linux kernel (common on CentOS 7/RHEL 7)
  2. /etc/subuid and /etc/subgid files don't exist or are empty
  3. The dockremap user or group doesn't exist when using 'default' setting
  4. Subordinate UID/GID ranges are not configured for the remapping user
  5. Kernel was compiled without CONFIG_USER_NS support
  6. user.max_user_namespaces sysctl is set to 0
  7. SELinux policies are blocking user namespace creation

How to fix "Error response from daemon: user namespace remapping is not supported"

1Check if user namespaces are enabled in the kernel

First, verify whether your kernel supports user namespaces:

bash
cat /proc/sys/user/max_user_namespaces

If this returns 0 or the file doesn't exist, user namespaces are disabled. You can also check:

bash
cat /boot/config-$(uname -r) | grep CONFIG_USER_NS

Look for CONFIG_USER_NS=y. If it shows # CONFIG_USER_NS is not set, your kernel doesn't support this feature.

2Enable user namespaces on CentOS/RHEL 7

On CentOS 7 and RHEL 7, user namespaces are disabled by default. Enable them with these commands:

bash
# Add kernel boot parameters
sudo grubby --args="namespace.unpriv_enable=1 user_namespace.enable=1" --update-kernel="$(grubby --default-kernel)"

# Increase the user namespace limit
echo "user.max_user_namespaces=15000" | sudo tee -a /etc/sysctl.conf

# Apply sysctl changes immediately (or reboot)
sudo sysctl -p

A reboot is required for the kernel parameters to take effect:

bash
sudo reboot
3Enable user namespaces on modern systems (Ubuntu/Debian/Fedora)

On modern systems, user namespaces are usually enabled but may be limited. Check and increase the limit:

bash
# Check current limit
sysctl user.max_user_namespaces

# If it's 0, enable user namespaces
echo "user.max_user_namespaces=28633" | sudo tee /etc/sysctl.d/99-userns.conf
sudo sysctl --system

On some Ubuntu systems with AppArmor restrictions:

bash
# Check if unprivileged user namespaces are restricted
cat /proc/sys/kernel/unprivileged_userns_clone

# If 0, enable it
echo 1 | sudo tee /proc/sys/kernel/unprivileged_userns_clone
4Create the subuid and subgid files

The /etc/subuid and /etc/subgid files must exist for user namespace remapping to work:

bash
# Create the files if they don't exist
sudo touch /etc/subuid /etc/subgid

These files define which subordinate UID/GID ranges can be used by each user for namespace remapping.

5Create the dockremap user and configure mappings

When using "userns-remap": "default", Docker expects a user called dockremap:

bash
# Create the dockremap user (system user, no home directory, no login)
sudo useradd -r -s /bin/false dockremap

# Add subordinate UID/GID mappings
# This maps container UID 0 to host UID 500000, with 65536 available IDs
echo "dockremap:500000:65536" | sudo tee -a /etc/subuid
echo "dockremap:500000:65536" | sudo tee -a /etc/subgid

Choose a starting UID (like 500000) that doesn't overlap with existing users on your system. The range 65536 provides enough IDs for typical container workloads.

6Configure Docker daemon for user namespace remapping

Edit or create /etc/docker/daemon.json:

bash
sudo nano /etc/docker/daemon.json

Add the userns-remap configuration:

json
{
  "userns-remap": "default"
}

Or specify a custom user:

json
{
  "userns-remap": "dockremap"
}

Save the file and restart Docker:

bash
sudo systemctl restart docker
7Verify user namespace remapping is working

After restarting Docker, verify the configuration:

bash
docker info | grep -i userns

You should see output like:

bash
Security Options: userns

Check the Docker root directory - it should include the UID mapping:

bash
docker info | grep "Docker Root Dir"

With userns-remap enabled, this will show something like /var/lib/docker/500000.500000 instead of just /var/lib/docker.

Test with a container:

bash
docker run --rm alpine id

Inside the container, this shows uid=0(root), but processes are actually running as an unprivileged user on the host.

8Disable userns-remap if not needed

If you don't need user namespace remapping and just want Docker to work, remove the configuration:

bash
# Edit daemon.json
sudo nano /etc/docker/daemon.json

Remove the "userns-remap" line or the entire file if it only contained that setting.

bash
# Restart Docker
sudo systemctl restart docker

This reverts to standard Docker behavior where container root equals host root (inside the container's namespace).

Advanced notes

Security Trade-offs:
User namespace remapping significantly improves container isolation. With userns-remap enabled, a container breakout that achieves root access only gains privileges as an unprivileged user on the host. However, this feature has compatibility implications:

- --privileged containers won't work without --userns=host
- --pid=host and --network=host are incompatible
- Some volume drivers may not support remapped UIDs
- Existing images and containers become invisible (stored in a different directory)

Kernel Configuration Requirements:
The kernel must be compiled with CONFIG_USER_NS=y. Most modern distributions include this, but enterprise distributions like RHEL 7 disable it by default for stability reasons. Check with:

bash
zcat /proc/config.gz 2>/dev/null | grep USER_NS || cat /boot/config-$(uname -r) | grep USER_NS

SELinux Interactions:
On SELinux-enabled systems (RHEL, CentOS, Fedora), you may encounter additional restrictions. If user namespaces work but containers fail:

bash
# Check for SELinux denials
sudo ausearch -m avc -ts recent | grep userns

# Temporarily set permissive mode for testing
sudo setenforce 0

Volume Permission Issues:
With userns-remap, files created in volumes will be owned by the remapped UID (e.g., 500000) on the host. To share data between host and container:

bash
# Use named volumes (Docker manages permissions)
docker volume create mydata
docker run -v mydata:/data alpine touch /data/file

# Or adjust host directory ownership
sudo chown -R 500000:500000 /path/to/host/dir

Per-Container Override:
To run a specific container without user namespace remapping (while keeping it enabled globally):

bash
docker run --userns=host --rm alpine id

This is useful for containers that require true root access, like system monitoring tools.

Rootless Docker Alternative:
For even stronger isolation, consider rootless Docker which runs the entire daemon as a non-root user:

bash
dockerd-rootless-setuptool.sh install

Rootless Docker provides similar security benefits without requiring kernel-level user namespace configuration.

Frequently asked questions

What does "Error response from daemon: user namespace remapping is not supported" mean?
User namespace remapping is an advanced Docker security feature that isolates container root users from the host's root user. When enabled, container processes running as root (UID 0) are mapped to an unprivileged high-numbered UID on the host, preventing privilege escalation attacks. This error appears because: - The Linux kernel on your host does not have user namespace support enabled - The required configuration files (/etc/subuid and /etc/subgid) are missing or misconfigured - The Docker daemon is configured to use userns-remap, but the system cannot support it - On older systems like CentOS 7 or RHEL 7, user namespaces are disabled by default in the kernel The Docker daemon checks for user namespace support at startup.
How do I fix "Error response from daemon: user namespace remapping is not supported"?
This error occurs when Docker's user namespace remapping feature (userns-remap) is enabled but the host kernel doesn't support user namespaces, or required configuration files are missing. The fix involves enabling kernel support for user namespaces and properly configuring the /etc/subuid and /etc/subgid files.
What causes "Error response from daemon: user namespace remapping is not supported"?
User namespaces are disabled in the Linux kernel (common on CentOS 7/RHEL 7) /etc/subuid and /etc/subgid files don't exist or are empty The dockremap user or group doesn't exist when using 'default' setting
Is the "Error response from daemon: user namespace remapping is not supported" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading