How to fix Error response from daemon: CPU period must be between 1000 and 1000000 in Docker

First, check what CPU period value you're trying to set. The error occurs when the value is outside the valid range of 1000-1000000 microseconds.

# Check if you're using --cpu-period in your command
docker run --cpu-period=500 myimage  # Error: too low (500 < 1000)
docker run --cpu-period=2000000 myimage  # Error: too high (2000000 > 1000000)

For existing containers, inspect the current CPU period:

docker inspect --format='{{.HostConfig.CpuPeriod}}' <container_name>

The default value is 100000 (100ms). A value of 0 means no limit is set.

Set the CPU period to a value between 1000 and 1000000 microseconds:

# Default and recommended value (100ms)
docker run --cpu-period=100000 --cpu-quota=50000 myimage

# Shorter period for more responsive throttling (10ms)
docker run --cpu-period=10000 --cpu-quota=5000 myimage

# Longer period for less overhead (500ms)
docker run --cpu-period=500000 --cpu-quota=250000 myimage

Valid range reference:
| Value | Meaning |
|-------|---------|
| 1000 | 1 millisecond (minimum) |
| 10000 | 10 milliseconds |
| 100000 | 100 milliseconds (default) |
| 500000 | 500 milliseconds |
| 1000000 | 1 second (maximum) |

For most use cases, the --cpus flag is simpler and less error-prone:

# Limit container to 0.5 CPU cores
docker run --cpus=0.5 myimage

# Limit container to 2 CPU cores
docker run --cpus=2 myimage

# Limit container to 1.5 CPU cores
docker run --cpus=1.5 myimage

The --cpus flag internally converts to --cpu-period and --cpu-quota:
- --cpus=0.5 is equivalent to --cpu-period=100000 --cpu-quota=50000
- --cpus=1.5 is equivalent to --cpu-period=100000 --cpu-quota=150000

This approach avoids period validation errors and is easier to understand.

In Docker Compose, use the cpus key under deploy.resources for simplicity:

version: '3.8'
services:
  myservice:
    image: myimage
    deploy:
      resources:
        limits:
          cpus: '0.5'
        reservations:
          cpus: '0.25'

If you need to use cpu_period explicitly (legacy Compose format):

version: '2.4'
services:
  myservice:
    image: myimage
    cpu_period: 100000
    cpu_quota: 50000

Note: The cpu_period and cpu_quota keys are only available in Compose file version 2.x. For version 3.x, use deploy.resources.limits.cpus instead.

If you need to modify CPU settings on a running container, use docker update:

# Update using --cpus (recommended)
docker update --cpus=0.5 <container_name>

# Update using --cpu-period and --cpu-quota
docker update --cpu-period=100000 --cpu-quota=50000 <container_name>

Verify the update was applied:

docker inspect --format='CpuPeriod: {{.HostConfig.CpuPeriod}}, CpuQuota: {{.HostConfig.CpuQuota}}' <container_name>

Note: Changes take effect immediately without restarting the container.

The CPU period and quota work together to limit CPU usage:

CPU Usage = cpu_quota / cpu_period

Examples:
| Period | Quota | CPU Usage |
|--------|-------|-----------|
| 100000 | 50000 | 50% of 1 CPU |
| 100000 | 100000 | 100% of 1 CPU |
| 100000 | 200000 | 200% (2 CPUs) |
| 50000 | 25000 | 50% of 1 CPU |

Choosing period values:
- Shorter periods (10000-50000): More responsive throttling, higher scheduling overhead
- Default period (100000): Good balance for most workloads
- Longer periods (200000-1000000): Lower overhead, but bursty behavior

For most applications, stick with the default period of 100000 and adjust only the quota (or use --cpus).