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

First, verify whether your kernel supports user namespaces:

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:

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.

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

# 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:

sudo reboot

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

# 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:

# 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

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

# 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.

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

# 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.

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

sudo nano /etc/docker/daemon.json

Add the userns-remap configuration:

{
  "userns-remap": "default"
}

Or specify a custom user:

{
  "userns-remap": "dockremap"
}

Save the file and restart Docker:

sudo systemctl restart docker

After restarting Docker, verify the configuration:

docker info | grep -i userns

You should see output like:

Security Options: userns

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

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:

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.

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

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

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

# Restart Docker
sudo systemctl restart docker

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