19.2.1.2 Run Detached Option

The detached option (-d or --detach) runs a container in the background, returning control to the calling shell immediately after the container starts. Without -d, docker run keeps the terminal attached to the container's standard streams — stdin, stdout, and stderr — so the container's output is printed directly to the current shell and the shell is blocked until the container exits. With -d, the container starts and runs independently of the terminal session.

Basic Usage

docker run -d nginx:latest

Output:

3a4b5c6d7e8f1234567890abcdef1234567890abcdef1234567890abcdef1234

The only output is the full container ID. The container is now running in the background. The shell prompt returns immediately.

Why Detached Mode Is Used

Most production and long-running services — web servers, databases, message queues, background workers — are run detached. Keeping them attached would require an open terminal session to keep the container alive, and closing the terminal or losing the SSH connection would kill the container.

Detached mode makes containers behave like system services: they start, run, and are managed through separate commands rather than being tied to an interactive session.

Verifying a Detached Container Is Running

docker ps

CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS     NAMES
3a4b5c6d7e8f   nginx:latest   "/docker-entrypoint…"   10 seconds ago   Up 9 seconds    80/tcp    nifty_curie

Accessing the Output of a Detached Container

Since the output is no longer printed to the terminal, it must be retrieved with docker logs:

docker logs 3a4b5c6d7e8f

Or by name:

docker logs nifty_curie

To follow the log output in real time (equivalent to tail -f):

docker logs -f nifty_curie

Logs collect everything the container's process writes to stdout and stderr. They persist until the container is removed or the log driver changes behavior.

Attaching to a Detached Container After the Fact

If you need to connect to a running detached container's stdout/stderr:

docker attach nifty_curie

This re-attaches the terminal to the container's primary process. Pressing Ctrl+C here sends SIGINT to the container process, which may stop the container. To detach again without stopping: press Ctrl+P then Ctrl+Q.

To execute commands inside the running container without attaching to the primary process:

docker exec -it nifty_curie bash

This opens an independent interactive session inside the container without disturbing the primary process.

Detached Mode and Container Lifecycle

A detached container continues running until:

• Its main process exits naturally.
• docker stop or docker kill is called.
• A restart policy triggers a restart (if configured).
• The Docker daemon is stopped (unless --restart unless-stopped was specified).

Closing the terminal that launched the container has no effect on a detached container.

Detached Mode with Port Publishing

docker run -d -p 8080:80 --name web nginx:latest

The web server is now accessible at http://localhost:8080 while running fully in the background.

Detached Mode with Named Volumes

docker run -d \
  --name postgres-db \
  -e POSTGRES_PASSWORD=secret \
  -v pgdata:/var/lib/postgresql/data \
  postgres:15

The database runs in the background, persisting its data to a named volume.

Checking Container Status and Stopping It

# Check status
docker ps

# Stop gracefully
docker stop nifty_curie

# Verify it stopped
docker ps -a

Detached Mode vs. Interactive Mode

The --detach-keys Option

Docker allows customizing the key sequence used to detach from an attached container. The default is ctrl-p,ctrl-q. To change it for a specific run:

docker run -d --detach-keys="ctrl-x,x" nginx:latest

This is useful in environments where the default sequence conflicts with other keybindings.

Combining Detached with Automatic Removal

The --rm flag and -d can be combined. The container runs in the background and is automatically deleted when its process exits:

docker run -d --rm myapp:1.0.0

This is useful for batch jobs that run to completion: they start in the background without blocking the shell, and they do not leave stopped containers behind when they finish.