Skip to content
Blog

Disconnecting Containers and Pruning Stale Docker Networks

Exit containers, disconnect them safely, and prune the stale Compose networks littering your host — with filters, labels, and a dry-run routine that won't delete live stacks.

Published on • November 19, 2026

AI Assistant

Every docker compose up mints a network, and plenty of environments never see a matching docker compose down. Six months later docker network ls is a graveyard of <project>_default entries, and the fear of deleting something live keeps you from cleaning any of it. This post covers the whole lifecycle: detach a container cleanly, remove a network Docker refuses to delete, and prune the leftovers with filters that make it safe.

Disconnecting a running container

docker network disconnect pulls one network out from under a live container — no restart, no recreate:

docker network disconnect demo-tier-front proxy1
docker exec proxy1 ip route
default via 10.90.0.1 dev eth0
10.90.0.0/24 dev eth0 scope link  src 10.90.0.20

Before the disconnect, that route table also carried the frontend’s 192.168.80.0/20 link on eth1. After it, that interface and its routes are gone from the container’s network namespace — the container keeps running, and whatever it still has attached keeps working. Name resolution follows membership: peers on the removed network stop resolving, peers on remaining networks don’t flinch.

The disconnect reference states that “the container must be running to disconnect it from the network” and offers -f/--force to force the issue. Worth knowing: on Docker Engine 29, disconnecting an already stopped container also succeeded without complaint in testing. Follow the docs for scripting, don’t depend on the observed leniety.

Removing a network Docker won’t delete

Removal fails while anything is actively using the network — and the error is refreshingly specific:

docker network rm demo-tier-back
Error response from daemon: error while removing network: network demo-tier-back has active endpoints (name:"db1" id:"985a565c3e98", name:"dual2" id:"e4cd1c87eb48", name:"proxy1" id:"f9d9145252058")

The fix is in the error: disconnect (or remove) the listed containers, then retry. docker network rm accepts multiple names and reports success or failure per network; -f suppresses only the “network does not exist” error, not active endpoints.

Here’s the nuance that surprises people: only running containers count as active endpoints. A network whose only container has exited removed cleanly in testing:

docker network ls -f dangling=true --format '{{.Name}}'   # t1 listed — c1 is stopped
docker network rm t1                                      # succeeds
t1

But that’s also a trap — start the orphaned container afterwards and it can’t come up:

docker start c1
Error response from daemon: failed to set up container networking: network d88a74551a76... not found

So the safe order is: disconnect or remove containers first, then remove the network, and never assume a stopped container’s network config will survive network deletion.

Why networks pile up

  • Compose projects create networks on every up — named <project>_default — and remove them on down. The compose down reference confirms the default scope: containers for services in the file, networks defined in the networks section, and the default network. Verified live: docker compose down printed Network democompose_default Removed.
  • down -v is a volume flag, not a network flag. It adds named and anonymous volumes to the removal — networks are removed either way. External networks are never removed by down.
  • Nobody ran down. docker stop, a crashed host, or deleting the compose file all leave the network behind. Exited containers keep their attachment, which is why the network lingers as dangling until the containers go too.
  • docker rm doesn’t sweep networks up either. Removing every container off a network leaves the network itself in place — a session cleanup here saw all containers vanish under rm -f while every network still needed an explicit network rm. Networks disappear only when something asks: down, rm, or prune.
  • Projects get renamed. Old project name, old label, old network — the new project creates fresh ones and the old set is orphaned.

Finding candidates: docker network ls filters

The ls reference documents these filters: driver, id, label, name, scope, and type (custom vs builtin) — and notes that multiple ls filters combine as OR:

docker network ls --filter driver=bridge
docker network ls --filter type=custom
docker network ls --filter label=com.docker.compose.project=myproj
docker network ls --filter name=foo        # substring match

One filter you’ll see in the wild isn’t on that list but works: dangling. It matches networks with no running containers attached — stopped containers still count as dangling:

docker network ls --filter dangling=true
NETWORK ID     NAME                  DRIVER    SCOPE
f8a81aeffd4e   demo-front            bridge    local
62f3e97710d4   demo-ipam             bridge    local
...

That output is your dry run: exactly the set docker network prune would consider (prune defines unused as “not referenced by any containers,” and bridge, host, and none are never pruned).

Make the dry run scriptable while you’re at it — .Name, .Driver, .CreatedAt, .Labels, and .Internal are all valid --format placeholders on ls:

docker network ls --filter dangling=true --format '{{.Name}} {{.CreatedAt}}'
myproj_default 2026-11-19 08:12:44.120394762 +0000 UTC
oldstack_default 2026-09-02 14:31:07.884120005 +0000 UTC

Sort by creation time, inspect anything you don’t recognize, and the oldest names are almost always the safest first deletes.

Labels: your safety net

Compose labels every network it owns, which is what makes bulk cleanup safe:

docker network inspect democompose_default --format '{{json .Labels}}'
{"com.docker.compose.config-hash":"a9c80e0...","com.docker.compose.network":"default",
 "com.docker.compose.project":"democompose","com.docker.compose.version":"5.5.0"}

com.docker.compose.project ties a network to its project — filter on it to touch only that project’s leftovers, or use label!= on prune to protect networks that lack a label (your hand-created ones). The prune reference supports until and label filters with precise semantics: different keys AND together, the same key ORs — --filter label=foo --filter until=24h means “has label foo and older than 24h.” until itself takes Go duration strings (10m, 1h30m) measured against the daemon’s clock, Unix timestamps, or RFC3339-style dates, so “everything older than the last deploy” is expressible — not just “older than a day.”

A safe cleanup routine

Dry run first, prune with a fence around it second:

# 1. See what's dangling (no running containers)
docker network ls --filter dangling=true

# 2. Spot-check anything you don't recognize
docker network inspect <name> --format '{{.Labels}} {{range .Containers}}{{.Name}} {{end}}'

# 3. Prune only old, only-unlabeled-if-you-wish, with confirmation
docker network prune --filter until=24h

# 4. Or scope it to one project's label and skip the prompt
docker network prune -f --filter label=com.docker.compose.project=oldproj

Answering n at the WARNING! This will remove all custom networks not used by at least one container prompt aborts without deleting anything — run it once just to see the warning. For a single network, docker network rm <name> gives per-item control, and the docs even show a batch form — docker network rm $(docker network ls --filter type=custom -q) — which is fine on throwaway hosts and reckless anywhere else, since every custom network in scope is a candidate and only running containers stop it.

The bottom line

Cleanup is three moves: disconnect to detach a container from one network, rm to delete a network once its active endpoints are gone (running containers block it, exited ones don’t — but their start will break), and prune with until/label filters to sweep Compose’s leftovers. Run docker network ls --filter dangling=true as your dry run, treat com.docker.compose.project labels as the fence that keeps you off live stacks, and run docker compose down while the compose file still exists — it’s the cheapest fix of all.

Further reading