Stop and Remove Compose Services

You've built a multi-service application with docker compose up, and everything is running smoothly. But now you need to stop those services — maybe to free up resources, test a new configuration, or deploy an update. Simply killing the terminal or hitting Ctrl+C can leave dangling containers, networks, and volumes that cause conflicts next time. That's where properly stopping and removing Compose services comes in.

The problem this lesson solves

When you run docker compose up, Compose creates containers, networks, and optionally volumes for your services. Shutting down the application isn't as simple as stopping the containers. Leftover resources can:

• Consume disk space — stopped containers, unused networks, and anonymous volumes linger.
• Block port bindings — a stopped container still holds a port if not removed.
• Cause stale data — databases may retain test data from previous runs.
• Confuse other tools — CI/CD pipelines or other projects may misinterpret old containers.

The core pain is that docker stop only halts containers but doesn't clean up. When you need to rebuild cleanly or start fresh, you must remove those services completely. This lesson shows you how to do that efficiently with Docker Compose.

Core concept / mental model

Think of Compose services as a set of Lego bricks (containers, networks, volumes) arranged according to a blueprint (the docker-compose.yml file).

• docker compose stop — freezes the bricks in place. The containers are paused without deleting them. You can restart them later with docker compose start, and all data persists.
• docker compose down — disassembles the entire structure. It stops all services and removes the containers, networks, and — optionally — volumes and images.

Pro tip: Use docker compose down when you want a clean slate for a fresh up. Use docker compose stop when you only need a temporary pause.

Key definitions

How it works step by step

Follow this logical progression to understand the lifecycle of stopping and removing Compose services.

Step 1: Check current Compose project

Before stopping, see what is currently running:

docker compose ps

This shows all services defined in the Compose file. Each has a status (Up, Paused, Exited).

Step 2: Stop services temporarily

Use docker compose stop to halt all containers without removal:

docker compose stop

Containers are stopped but still exist. Run docker compose ps again to see Exit 0 status. You can restart them with:

docker compose start

Step 3: Remove containers and networks (but keep volumes)

For a clean teardown that preserves persistent data, use:

docker compose down

This removes: - All containers of the project - Default network(s) created by Compose - But not volumes declared in volumes: or bound mounts

Step 4: Remove everything — including volumes

If you want to delete database data, cache, or temp files, add the -v flag:

docker compose down -v

This removes anonymous volumes and named volumes defined in volumes:. Beware — data loss is permanent.

Step 5: Remove images as well (full cleanup)

In CI/CD or when testing image changes, you may want to also delete the pulled or built images:

docker compose down --rmi all

This removes all images used by any service in the Compose file. You can also choose --rmi local to remove only images built locally.

Hands-on walkthrough

Let's practice with a simple web service + database example.

1. Create a sample docker-compose.yml

version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
  db:
    image: postgres:13
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

2. Start the services

docker compose up -d

Expected output:

Creating network "myapp_default" with driver "bridge"
Creating myapp_web_1 ... done
Creating myapp_db_1  ... done

Check running state:

docker compose ps

You'll see both services Up.

3. Stop the services (temporary)

docker compose stop

Expected output:

Stopping myapp_db_1  ... done
Stopping myapp_web_1 ... done

Now docker compose ps shows Exit 0 for both.

4. Start them again to verify persistence

docker compose start

Services return to Up. Data in the Postgres volume is still there.

5. Remove services but keep volumes

docker compose down

Expected output:

Stopping myapp_web_1 ... done
Stopping myapp_db_1  ... done
Removing myapp_web_1 ... done
Removing myapp_db_1  ... done
Removing network myapp_default

Note: the pgdata volume remains. You can verify with:

docker volume ls | grep pgdata

6. Start fresh without data

docker compose down -v
docker compose up -d

The Postgres volume is deleted and recreated with a clean database.

Compare options / when to choose what

Variations

• Stop a single service: docker compose stop web stops only the web service.
• Remove a single container: docker compose rm db removes the stopped db container (must stop first).
• Remove without stopping: docker compose down automatically stops containers first.

Troubleshooting & edge cases

Error: "no configuration file provided: not found"

You're in the wrong directory or the Compose file is named differently. Use -f:

docker compose -f /path/to/docker-compose.yml down

Error: "service 'web' is not running"

Running docker compose stop on already-stopped services is harmless — it outputs "Stopping" but does nothing. Similarly, docker compose down works fine on stopped services.

Error: "Failed to remove network myapp_default: network is still in use"

Another container outside Compose is attached to the network. Remove that container first, or force remove with docker network rm -f myapp_default (manual).

Problem: Containers not removed after docker compose down

You might have run docker compose up without the config file or with a different project name. Use:

docker compose -p myproject down

where myproject is the actual project name (defaults to directory name).

Edge case: Orphaned containers

If you change the Compose file (e.g., remove a service), old containers won't be removed by down. Use --remove-orphans:

docker compose down --remove-orphans

Common mistakes

• Running docker compose stop and expecting a clean state — stopped containers still consume space and port mappings.
• Using docker compose down -v without backing up database volumes — data is gone forever.
• Forgetting to specify -f when working outside the project directory.
• Assuming docker compose rm stops containers (it doesn't; only removes stopped ones).
• Confusing docker compose down with docker compose stop when you need to restart later.

What you learned & what's next

You now understand how to properly stop and remove Compose services:

• Stopping preserves resources for a quick restart.
• Removing cleans up containers, networks, and optionally volumes/images.
• docker compose down is the go-to command for teardown.
• Use flags (-v, --rmi) for deeper cleanup.
• Troubleshoot common errors like missing config files or orphans.

This skill is essential for development workflows, CI/CD pipelines, and production maintenance. Your next step is learning how to view logs and debug services, ensuring you can diagnose issues when things don't work as expected.

Pro tip: Create an alias like dc-down for docker compose down --remove-orphans to keep your environment clean in daily use.