How to Set Docker Container Memory Limits

In this tutorial, you'll learn about How to Set Docker Container Memory Limits. We cover key concepts, practical examples, and best practices.

The Problem

A Docker container uses all available system memory and gets killed by the OOM killer, or you see docker container exited with code 137 (OOM exit code 137 = 128 + 9, where 9 is SIGKILL). Unbounded containers can consume host resources and destabilize other services. By default, Docker containers have no memory limit — they can use as much RAM as the host provides. This is dangerous in production environments where multiple containers share a single host: one leaking or memory-intensive container can cause all other containers and even the host itself to run out of memory, leading to cascading failures.

Quick Fix

1. Run a container with a memory limit

docker run -d --name my-app --memory="512m" --memory-swap="1g" nginx:alpine

• --memory="512m" limits RAM to 512 MB
• --memory-swap="1g" sets total memory+swap to 1 GB (must be >= memory)
• If --memory-swap is the same as --memory, the container has no swap access
• If --memory-swap is unset, it defaults to twice the memory limit

2. Set memory limits in Docker Compose

services:
  app:
    image: nginx:alpine
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 128M

Note: deploy resources require Docker Compose v3 and are used by docker stack deploy. For docker-compose up, use these in version 2 format:

services:
  app:
    image: nginx:alpine
    mem_limit: 512m
    mem_reservation: 128m
    cpus: 0.5

3. Check current memory usage

docker stats --no-stream

Expected output:

CONTAINER ID   NAME      CPU %     MEM USAGE / LIMIT   MEM %     NET I/O
abc123def456   my-app    0.15%     42.3MiB / 512MiB    8.26%     1.2kB / 648B

Use docker stats without --no-stream for live monitoring (Ctrl+C to exit).

4. Update memory limit on a running container

You cannot change the memory limit on a running container with the default runc runtime. Stop and recreate it:

docker stop my-app && docker rm my-app
docker run -d --name my-app --memory="1g" nginx:alpine

5. Check if OOM killer killed your container

docker inspect my-app --format='{{.State.OOMKilled}}'

Returns true if the container was killed due to out-of-memory.

Inspect Container Configuration

docker inspect <container-id> --format '{{json .Config}}' | python3 -m json.tool
# {
#   "Hostname": "abc123",
#   "Env": ["PATH=/usr/local/bin:..."],
#   "Cmd": ["node", "app.js"]
# }

Use docker inspect to examine the full configuration of a container. This reveals misconfigurations in environment variables, command arguments, and network settings that may not appear in logs.

Prevention

• Always set --memory for production containers — even a soft limit prevents runaway resource usage
• Monitor with docker stats and set alerts at 80% of the limit
• Use Docker Compose resource reservations in production deployments
• Reserve memory (not just limit it) so the scheduler knows the container's baseline needs
• For JVM-based applications, set -Xmx to 75% of the Docker memory limit to leave room for JVM overhead