Docker containers have an interactive mode that lets you attach your terminal’s input and output streams to the container’s process. Pressing Ctrl-C will usually terminate that process, causing the container to stop. Here’s to detach from a session without stopping the container.

Detaching Without Stopping

Docker supports a keyboard combination to gracefully detach from a container. Press Ctrl-P, followed by Ctrl-Q, to detach from your connection.

You’ll be dropped back into your shell but the previously attached process will remain alive, keeping your container running. You can check this by using docker ps to get a list of running containers.

Pressing Ctrl-C or running the exit command will usually kill the container’s foreground process unless it’s been specially configured. A Docker container needs to have a running foreground process; a container without one will enter the stopped state.

Changing the Detach Keyboard Sequence

You can change the detach sequence to match your preference or avoid a conflict with keyboard shortcuts honored by your application. Add a detachKeys property to your ~/.docker/config.json file to specify the keys you want to use.

Docker supports the a-z characters and @, ^, and _, symbols, as well as the left bracket sign ([) and two back slashes (). These are all used in conjunction with the Ctrl- key; letters may also be used individually, without Ctrl.

Key sequences are expressed as a comma-separated list:

This example would detach from the container when you press Ctrl-D immediately followed by the d key.

Changing the Sequence on a Per-Container Basis

Beyond changing your global configuration, Docker accepts detachKeys overrides on a per-container and per-attachment basis. Add the –detach-keys flag to commands which can attach to container processes to set a specific sequence.

The commands which support this are:

docker run docker start docker exec docker attach

Here’s how to attach to a container and then use Ctrl-d, followed by an underscore, to detach:

The –detach-keys flag uses the same key sequence format as the detachKeys config option. The flag overrides your docker.json setting; this in turn overrides Docker’s default Ctrl-P/Ctrl-Q sequence.

Detaching When The Keyboard Sequence Won’t Work

Sometimes you might encounter a container process that refuses to detach, even when you issue the keyboard sequence. This can happen if the container’s input stream isn’t connected to your terminal (-i flag) or it has no pseudo-TTY allocated (-t flag). You could also come across this issue if your container’s process handles the detach key sequence and you didn’t override it when you attached.

It’s still possible to detach your terminal from the container under these circumstances. You need to temporarily open another shell window and use it to kill the docker.attach process that’s keeping the attachment active.

First find the process ID of the attachment process:

Use the output from ps to identify the docker.attach process you need to kill. The command in the CMD column should identify the attachment you’re looking for. Note down the relevant PID number and use the kill command to kill this process:

You should see your original shell detach from your Docker container and revert to a normal operating state. You can now close the second shell and continue using the original one.

This technique works by killing the Docker CLI process that attached the terminal to the container, not the process within the container that keeps it running. Your original terminal becomes usable again and the container remains up.

Reattaching to Your Container

You can reattach to containers using the docker attach command. This automatically attaches your terminal’s input, output, and error streams to the specified container:

All three streams are connected by default. You can omit the input stream by passing the –no-stdin flag. The container’s output will be streamed into your terminal but you won’t be able to supply any input.

Use the keyboard sequence again to detach, or Ctrl-C to stop the process and container. If you use Ctrl-C or exit, docker attach will set the $? variable in your shell correctly so you can inspect the container’s exit code.

Summary

The correct way to detach from a Docker container is a fairly obscure keyboard sequence that drops you back into your shell. You can customize this sequence to increase memorability and avoid any conflicts with your container’s keyboard handling.

Keyboard detach sequences can be ineffective in some circumstances. It’s still possible to detach from your container by identifying and killing the process that’s supporting the attachment. Regular Unix commands such as ps and kill should be used in this scenario.

Finally, if you want your container to be permanently detached, start it with the -d flag (docker run -d my-image:latest). This will send the container straight into the background and emit no output to your shell. Detached containers are always visible using the docker ps command and can be stopped with docker stop my-container.