How to fix Error response from daemon: CPU quota must be greater than 1000 in Docker

DockerINTERMEDIATELOWUpdated Dec 6, 2025· 207 views

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.

Quick fix

Fixes Error response from daemon: CPU quota must be greater than 1000

# 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 myimage
  1. Understand the CPU quota minimum requirement
  2. Use the --cpus flag instead (recommended)
  3. Fix the --cpu-quota value
  4. Update Docker Compose configuration
docker — error
# 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 myimage
Error response from daemon: CPU quota must be greater than 1000

What this error means

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.

Typical symptoms

  • Docker run command fails immediately with 'CPU quota must be greater than 1000' error
  • Docker Compose up fails when cpu_quota is set to 1000 or below
  • Container creation fails with daemon error about CPU quota
  • docker update command rejected when trying to set low CPU quota
  • CI/CD pipeline fails at container start step with CPU resource error

Common causes

  1. Explicitly setting --cpu-quota to 1000 or a smaller value
  2. Miscalculating quota when trying to achieve very low CPU limits
  3. Copy-pasting configuration without understanding microsecond units
  4. Using --cpu-quota without --cpu-period, resulting in an unintended ratio
  5. Attempting to limit container to less than 1% of a CPU core with improper values
  6. Confusing milliseconds with microseconds (1ms = 1000 microseconds)

How to fix "Error response from daemon: CPU quota must be greater than 1000"

1Understand the CPU quota minimum requirement

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:

bash
# 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 myimage
2Use the --cpus flag instead (recommended)

The simplest solution is to use the --cpus flag, which handles the period/quota math automatically and validates input:

bash
# 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 myimage

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

3Fix the --cpu-quota value

If you need to use --cpu-quota directly, ensure the value is greater than 1000:

bash
# 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 myimage

To achieve very low CPU limits while respecting the minimum quota, adjust the cpu-period:

bash
# 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 myimage

Note: Very low CPU limits can cause extreme slowdowns. The container may become practically unusable.

4Update Docker Compose configuration

In Docker Compose, use either the cpus key (recommended) or cpu_quota:

Using cpus (Docker Compose 3.x with deploy):

yaml
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):

yaml
version: "2.4"
services:
  myapp:
    image: myimage
    cpus: 0.5

Using cpu_quota (legacy, ensure value > 1000):

yaml
version: "2.4"
services:
  myapp:
    image: myimage
    cpu_period: 100000
    cpu_quota: 50000  # Must be > 1000

Run with resource limits enabled:

bash
docker compose up
# or for older versions with deploy section:
docker compose --compatibility up
5Update existing container CPU limits

To update CPU limits on a running container, use docker update:

bash
# 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 mycontainer

Verify the update:

bash
docker inspect --format='{{.HostConfig.CpuQuota}}' mycontainer
docker inspect --format='{{.HostConfig.CpuPeriod}}' mycontainer

Note: 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.

6Verify CPU limits are applied correctly

After setting CPU limits, verify they are working:

bash
# 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 value

The 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):

bash
# 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_us

Advanced notes

Understanding 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")

bash
# Cgroup v2 check
cat /sys/fs/cgroup/docker/<container_id>/cpu.max
# Output: "50000 100000" means quota=50000, period=100000

Why 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):

yaml
resources:
  limits:
    cpu: "500m"  # Equivalent to --cpus=0.5

Kubernetes converts this to appropriate cgroup values automatically.

Frequently asked questions

What does "Error response from daemon: CPU quota must be greater than 1000" mean?
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.
How do I fix "Error response from daemon: CPU quota must be greater than 1000"?
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.
What causes "Error response from daemon: CPU quota must be greater than 1000"?
Explicitly setting --cpu-quota to 1000 or a smaller value Miscalculating quota when trying to achieve very low CPU limits Copy-pasting configuration without understanding microsecond units
Is the "Error response from daemon: CPU quota must be greater than 1000" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading