docker-compose-down

Stop and remove all containers and networks

$ docker compose down

$ docker compose down --rmi all

$ docker compose down --rmi local

$ docker compose down [[-v|--volumes]]

$ docker compose down --remove-orphans

$ docker compose [[-f|--file]] [path/to/config] down

$ docker compose down [[-t|--timeout]] [timeout]

$ docker compose down --remove-orphans [[-v|--volumes]]

docker-compose [OPTIONS] down [DOWN_OPTIONS]
Example:
docker-compose -f production.yml -p myapp down --rmi all -v --remove-orphans

-f ..., --file ...
    Specify one or more Compose files to use. If multiple files are specified, Compose combines them into a single configuration.

-p , --project-name
    Specify an alternate project name. Defaults to the current directory name.

--rmi
    Remove images. can be 'all' to remove all images used by any service, or 'local' to remove only images that don't have a custom tag applied (i.e., local images created by 'docker-compose build').

-v, --volumes
    Remove named volumes declared in the 'volumes' section of the Compose file and anonymous volumes attached to containers. By default, only anonymous volumes are removed; this option ensures named volumes are also removed.

--remove-orphans
    Remove containers for services that are not defined in the Compose file but were previously part of the project (e.g., from a previous 'up' command with a different service set).

-t , --timeout
    Specify a shutdown timeout in seconds. Compose will wait for this duration for containers to stop before killing them. Default is 10 seconds.

docker-compose down is a crucial command for cleaning up a Docker Compose application environment. It gracefully stops running containers, then removes the containers themselves, along with any networks created by docker-compose up. By default, it also removes anonymous volumes attached to containers. This command is the inverse of docker-compose up, ensuring that resources allocated for a specific Docker Compose project are properly de-provisioned and freed. It's essential for developers to use down after they are done working with an application or when they need to rebuild the environment from scratch, preventing resource accumulation and potential conflicts. Additional options allow for more aggressive cleanup, such as removing named volumes, images, or orphaned containers not explicitly defined in the Compose file.

• Using --volumes will delete data stored in named volumes, which is often persistent. Always ensure data is backed up or no longer needed before using this option.
• --rmi all can remove images that might be shared by other projects or applications. Use with caution.
• docker-compose down operates within the context of the current project (defined by the directory name or --project-name). It will not affect containers or resources from other Docker Compose projects.
• down does not remove external networks or volumes that were pre-existing and merely referenced in the Compose file. It only removes those created by docker-compose up.

While docker-compose stop only stops the running containers, leaving them in an exited state (and preserving their data in volumes), docker-compose down goes a step further. It stops the containers and then removes them entirely, along with any associated networks and, optionally, volumes and images. down is for full cleanup, while stop is for pausing a running application.

When docker-compose down is executed, it first sends a SIGTERM signal to the running containers, allowing them to perform a graceful shutdown within the specified timeout. If the containers do not stop within the timeout, a SIGKILL signal is sent to force termination.

The down command has been a fundamental part of Docker Compose since its inception (originally as fig). It provides a streamlined way to dismantle multi-container applications, evolving with the docker-compose CLI (version 1) which was a Python-based tool. Its functionality remains core to the new Docker Compose V2, now integrated as a Docker CLI plugin (docker compose), emphasizing its importance in the development lifecycle for managing ephemeral environments.

docker-compose(1), docker-compose up(1), docker-compose stop(1), docker-compose rm(1), docker(1)