This error occurs when you try to use the --pids-limit flag on a system where the Linux kernel does not have the pids cgroup controller enabled. The fix involves enabling CGROUP_PIDS in your kernel configuration or switching to cgroup v2 with proper systemd delegation.
The "pids limit is not supported on this platform" error indicates that Docker cannot enforce a process ID (PID) limit on your containers because your Linux kernel lacks support for the pids cgroup controller. The pids cgroup controller was introduced in Linux kernel 4.3 and allows limiting the number of processes that can be created within a cgroup (and thus within a Docker container). This feature is crucial for preventing fork bombs, where a malicious or buggy process creates processes indefinitely until system resources are exhausted. Docker requires the kernel to be compiled with CONFIG_CGROUP_PIDS=y to enable this functionality. Without it, the --pids-limit flag on docker run, the pids_limit option in Docker Compose v2, or the deploy.resources.limits.pids option in Docker Compose v3/Swarm cannot be used. This error is common on older Linux kernels, some minimal or embedded Linux distributions, and when running Docker in rootless mode on cgroup v1 systems.
First, verify whether your kernel supports the pids cgroup controller:
# Check if pids controller is available
cat /proc/cgroups | grep pidsIf this returns a line like pids 0 1 1, the pids controller is available. If it returns nothing, your kernel lacks support.
Also check Docker's view of cgroup support:
docker info | grep -i pidsYou can also check kernel configuration:
# If available on your system
zcat /proc/config.gz | grep CGROUP_PIDS
# Or check boot config
grep CGROUP_PIDS /boot/config-$(uname -r)If CONFIG_CGROUP_PIDS is not set to 'y', your kernel needs to be recompiled or upgraded.
Determine which cgroup version your system uses:
# Check cgroup version
stat -fc %T /sys/fs/cgroup/- Output cgroup2fs means cgroup v2 (unified hierarchy)
- Output tmpfs means cgroup v1 (legacy hierarchy)
For cgroup v1, check if pids controller is mounted:
mount | grep cgroup | grep pids
# or
ls /sys/fs/cgroup/pidsIf the pids controller is not mounted, you may need to mount it manually or update your kernel.
The pids cgroup controller requires Linux kernel 4.3 or later. Check your current kernel version:
uname -rIf you're on an older kernel, upgrade to a newer version:
Ubuntu/Debian:
sudo apt update
sudo apt upgrade linux-generic
sudo rebootRHEL/CentOS/Fedora:
sudo dnf upgrade kernel
# or for older versions
sudo yum upgrade kernel
sudo rebootFor minimal distributions, you may need to install a full kernel package or recompile the kernel with CONFIG_CGROUP_PIDS=y enabled.
If you're running Docker in rootless mode, cgroup v2 is strongly recommended as it provides better support for resource limits including pids.
Enable cgroup v2 in GRUB:
# Edit GRUB configuration
sudo nano /etc/default/grub
# Add or modify this line
GRUB_CMDLINE_LINUX="systemd.unified_cgroup_hierarchy=1"
# Update GRUB
sudo update-grub # Debian/Ubuntu
# or
sudo grub2-mkconfig -o /boot/grub2/grub.cfg # RHEL/CentOS
# Reboot
sudo rebootAfter reboot, verify cgroup v2 is active:
stat -fc %T /sys/fs/cgroup/
# Should output: cgroup2fsFor rootless Docker with cgroup v2, you need to enable delegation of cgroup controllers to user sessions:
# Create systemd configuration directory
sudo mkdir -p /etc/systemd/system/[email protected]
# Create delegation configuration
sudo tee /etc/systemd/system/[email protected]/delegate.conf << 'EOF'
[Service]
Delegate=cpu cpuset io memory pids
EOF
# Reload systemd
sudo systemctl daemon-reload
# Restart user session or reboot
loginctl terminate-user $USERAfter logging back in, verify the controllers are delegated:
cat /sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/cgroup.controllersYou should see pids in the output.
After applying the fixes, verify that pids limit now works:
# Check Docker's capabilities
docker info 2>&1 | grep -i pids
# Test running a container with pids limit
docker run --rm --pids-limit=100 alpine cat /sys/fs/cgroup/pids.max
# For cgroup v1 systems
docker run --rm --pids-limit=100 alpine cat /sys/fs/cgroup/pids/pids.maxThe output should show 100 (or max if no limit is set).
For Docker Compose, test with:
version: '2.4'
services:
test:
image: alpine
command: cat /sys/fs/cgroup/pids.max
pids_limit: 100Or for Compose v3 with Swarm mode:
version: '3.9'
services:
test:
image: alpine
deploy:
resources:
limits:
pids: 100If you cannot upgrade your kernel or enable pids support, you can remove the pids limit from your Docker configuration as a workaround:
For docker run:
# Remove --pids-limit flag
docker run --memory=512m <image> # Without --pids-limitFor Docker Compose v2:
version: '2.4'
services:
app:
image: myapp
# Remove pids_limit line
mem_limit: 512mFor Docker Compose v3:
version: '3.9'
services:
app:
image: myapp
deploy:
resources:
limits:
memory: 512M
# Remove pids: lineWarning: Without pids limits, containers are vulnerable to fork bombs. Consider implementing application-level process limits or using ulimits as a partial mitigation:
docker run --ulimit nproc=100 <image>Understanding the pids cgroup controller: The pids controller limits the number of process IDs (PIDs) that can be allocated within a cgroup. This directly limits the number of processes and threads that can exist simultaneously. When the limit is reached, fork() and clone() system calls fail with EAGAIN.
Docker Compose version differences: The pids_limit option has different support across Compose versions:
- Compose v2.x files (version: '2.4'): Use pids_limit: 100 directly on the service
- Compose v3.x files: Use deploy.resources.limits.pids: 100 (only works in Swarm mode)
- Non-Swarm v3: Use docker compose run with docker-compose.override.yml containing v2.4 syntax, or use docker container update --pids-limit 100 <container> after start
Rootless Docker limitations on cgroup v1: When running rootless Docker on cgroup v1, the --cpus, --memory, and --pids-limit flags are silently ignored. This is because non-root users cannot access the cgroup filesystem in v1. Migrating to cgroup v2 with proper delegation is the only solution.
Kernel compilation: If you're building a custom kernel, ensure these options are enabled:
CONFIG_CGROUPS=y
CONFIG_CGROUP_PIDS=yKubernetes considerations: In Kubernetes, PID limits can be configured at the kubelet level using the --pod-max-pids flag (deprecated) or podPidsLimit in kubelet configuration. This requires kernel support on all nodes:
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
podPidsLimit: 1024Security implications: Without pids limits, a container can create unlimited processes, potentially:
- Exhausting system PIDs (default max is 32768 on many systems)
- Causing denial of service to other containers and the host
- Making the system unresponsive through fork bombs
Consider enabling pids limits as part of your container security baseline.
dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec