This error occurs when you set Docker's --cpu-quota flag to a value of 1000 microseconds or less. The CPU quota must exceed 1000 microseconds (1ms) to ensure meaningful CPU time allocation. Use the simpler --cpus flag or ensure your quota value is at least 1001.
The "CPU quota must be greater than 1000" error occurs when Docker rejects a CPU quota value that is too small. Docker uses the Linux CFS (Completely Fair Scheduler) to limit CPU usage through two related parameters: cpu-period and cpu-quota, both measured in microseconds. The cpu-period defines the length of the scheduling period (default: 100,000 microseconds or 100ms), while cpu-quota specifies how many microseconds the container can use within each period. For example, a quota of 50,000 with the default period limits the container to 50% of one CPU core. Docker enforces a minimum quota of 1001 microseconds (just over 1ms) because smaller values would create impractically short CPU time slices. A quota of 1000 microseconds or less would result in such frequent context switches that the container would barely make progress, effectively starving it of CPU resources. This minimum ensures containers receive at least a minimal usable CPU allocation per scheduling period.
Docker requires the CPU quota to be at least 1001 microseconds. This is because the Linux CFS scheduler needs a minimum time slice to be practical.
The relationship between cpu-period and cpu-quota determines CPU allocation:
- CPU limit = cpu-quota / cpu-period
- Default cpu-period is 100,000 microseconds (100ms)
- Minimum cpu-quota is 1001 microseconds
For example, to limit a container to 10% of one CPU:
# This works: 10000 / 100000 = 0.10 (10% CPU)
docker run --cpu-period=100000 --cpu-quota=10000 myimage
# This fails: quota too low
docker run --cpu-period=100000 --cpu-quota=1000 myimageThe simplest solution is to use the --cpus flag, which handles the period/quota math automatically and validates input:
# Limit to 0.5 CPUs (50% of one core)
docker run --cpus=0.5 myimage
# Limit to 0.1 CPUs (10% of one core)
docker run --cpus=0.1 myimage
# Limit to 2 CPUs (on multi-core systems)
docker run --cpus=2 myimageThe --cpus flag accepts decimal values from 0.001 upward. Internally, Docker converts this to appropriate cpu-period and cpu-quota values:
- --cpus=0.5 becomes --cpu-period=100000 --cpu-quota=50000
- --cpus=0.1 becomes --cpu-period=100000 --cpu-quota=10000
This is available in Docker 1.13 and later.
If you need to use --cpu-quota directly, ensure the value is greater than 1000:
# Minimum valid quota (with default 100ms period = ~1% CPU)
docker run --cpu-quota=1001 myimage
# 5% CPU limit
docker run --cpu-quota=5000 myimage
# 25% CPU limit
docker run --cpu-quota=25000 myimage
# 100% of one CPU (full core)
docker run --cpu-quota=100000 myimageTo achieve very low CPU limits while respecting the minimum quota, adjust the cpu-period:
# Limit to ~0.1% CPU by using a longer period
# 1001 / 1000000 = 0.001 (0.1% CPU)
docker run --cpu-period=1000000 --cpu-quota=1001 myimageNote: Very low CPU limits can cause extreme slowdowns. The container may become practically unusable.
In Docker Compose, use either the cpus key (recommended) or cpu_quota:
Using cpus (Docker Compose 3.x with deploy):
version: "3.9"
services:
myapp:
image: myimage
deploy:
resources:
limits:
cpus: "0.5"Using cpus directly (Docker Compose 2.x or 3.x without deploy):
version: "2.4"
services:
myapp:
image: myimage
cpus: 0.5Using cpu_quota (legacy, ensure value > 1000):
version: "2.4"
services:
myapp:
image: myimage
cpu_period: 100000
cpu_quota: 50000 # Must be > 1000Run with resource limits enabled:
docker compose up
# or for older versions with deploy section:
docker compose --compatibility upTo update CPU limits on a running container, use docker update:
# Update using --cpus (recommended)
docker update --cpus=0.5 mycontainer
# Update using quota directly (must be > 1000)
docker update --cpu-quota=50000 mycontainer
# Update both period and quota
docker update --cpu-period=100000 --cpu-quota=50000 mycontainerVerify the update:
docker inspect --format='{{.HostConfig.CpuQuota}}' mycontainer
docker inspect --format='{{.HostConfig.CpuPeriod}}' mycontainerNote: docker update may not work on all container runtimes or with certain cgroup configurations. If the update has no effect, you may need to recreate the container.
After setting CPU limits, verify they are working:
# Check current CPU configuration
docker inspect mycontainer | grep -E "(CpuPeriod|CpuQuota|NanoCpus)"
# Monitor CPU usage in real-time
docker stats mycontainer
# Run a CPU stress test inside the container
docker exec mycontainer sh -c "dd if=/dev/zero of=/dev/null &"
docker stats mycontainer # Should show CPU limited to your configured valueThe docker stats output will show the container's CPU percentage capped at your limit. For example, with --cpus=0.5, you should see CPU usage plateau around 50%.
To check cgroup values directly (Linux):
# Find container's cgroup
CONTAINER_ID=$(docker inspect --format='{{.Id}}' mycontainer)
cat /sys/fs/cgroup/cpu/docker/$CONTAINER_ID/cpu.cfs_quota_us
cat /sys/fs/cgroup/cpu/docker/$CONTAINER_ID/cpu.cfs_period_usUnderstanding CFS Scheduler: Docker uses the Linux Completely Fair Scheduler (CFS) bandwidth control. The CFS divides CPU time into periods and enforces quotas within each period. When a container exhausts its quota, it's throttled until the next period begins.
Cgroup v1 vs v2: The cpu-period and cpu-quota parameters map to different cgroup files:
- Cgroup v1: cpu.cfs_period_us and cpu.cfs_quota_us
- Cgroup v2: Combined into cpu.max (format: "quota period")
# Cgroup v2 check
cat /sys/fs/cgroup/docker/<container_id>/cpu.max
# Output: "50000 100000" means quota=50000, period=100000Why 1000 microsecond minimum?: The Linux kernel enforces this minimum to prevent scheduler thrashing. With quotas below 1ms, the overhead of context switching would dominate actual work, making the limit counterproductive.
Real-time scheduling: For containers requiring real-time scheduling (using --cpu-rt-runtime and --cpu-rt-period), different limits apply. Real-time scheduling requires specific kernel configuration and is typically only needed for specialized workloads.
Multi-CPU considerations: On multi-core systems, you can allocate more than 100% CPU:
- --cpus=2 allows use of 2 full CPU cores
- --cpu-quota=200000 with default period also equals 2 CPUs
- Maximum practical limit is the number of available CPU cores
Kubernetes translation: In Kubernetes, CPU limits are specified in CPU units (1 CPU = 1000m = 1000 millicores):
resources:
limits:
cpu: "500m" # Equivalent to --cpus=0.5Kubernetes converts this to appropriate cgroup values automatically.
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