Stop docker compose from orphaning anonymous volumes

Steps#

Steps 1 to 4 show the behaviour on your Docker with a throwaway project called anonvol; steps 5 to 7 change the script.

1. Create the test stack in an empty directory.

   mkdir -p anonvol && cd anonvol
   cat > compose.yaml <<'YAML'
   services:
     app:
       image: alpine:3.24.2
       command: sleep 600
       volumes:
         - /anon         # anonymous volume
         - named:/keep   # named volume
   volumes:
     named:
   YAML
   

   Expected: you are in anonvol/, and compose.yaml is the only file there.

2. Start it and read the labels of both volumes.

   $ docker compose -p anonvol up -d
    Image alpine:3.24.2 Pulling
    Image alpine:3.24.2 Pulled
    Network anonvol_default Creating
    Volume anonvol_named Creating
    Volume anonvol_named Creating
    Network anonvol_default Creating
    Volume anonvol_named Created
    Volume anonvol_named Created
    Network anonvol_default Created
    Network anonvol_default Created
    Container anonvol-app-1 Creating
    Container anonvol-app-1 Created
    Container anonvol-app-1 Starting
    Container anonvol-app-1 Started
   $ docker inspect -f '{{.Name}}{{range .Mounts}}{{println}}  {{.Type}} {{.Name}} -> {{.Destination}}{{end}}' anonvol-app-1
   /anonvol-app-1
     volume 1fca8d0c2829e9760baec3cf83f3e8a4cc2c493b3c2b3d88ddf1164532058243 -> /anon
     volume anonvol_named -> /keep
   $ A=$(docker inspect -f '{{range .Mounts}}{{if eq .Destination "/anon"}}{{.Name}}{{end}}{{end}}' anonvol-app-1)
   $ echo "$A"
   1fca8d0c2829e9760baec3cf83f3e8a4cc2c493b3c2b3d88ddf1164532058243
   $ docker volume inspect -f '{{json .Labels}}' "$A"
   {"com.docker.volume.anonymous":""}
   $ docker volume inspect -f '{{json .Labels}}' anonvol_named
   {"com.docker.compose.config-hash":"4456136bca9a68374890f14351c9dfc1be9e440fed2c7f0c2012e8157fdec197","com.docker.compose.project":"anonvol","com.docker.compose.version":"5.6.0","com.docker.compose.volume":"named"}
   

   Expected: the named volume carries com.docker.compose.project; the anonymous one carries only com.docker.volume.anonymous. Once its container is gone, nothing on an anonymous volume says which project made it.

3. Tear down with plain down and see the orphan.

   $ docker compose -p anonvol down
    Container anonvol-app-1 Stopping
    Container anonvol-app-1 Stopped
    Container anonvol-app-1 Removing
    Container anonvol-app-1 Removed
    Network anonvol_default Removing
    Network anonvol_default Removed
   $ docker volume ls --filter dangling=true --filter name="$A"
   DRIVER    VOLUME NAME
   local     1fca8d0c2829e9760baec3cf83f3e8a4cc2c493b3c2b3d88ddf1164532058243
   $ docker volume rm "$A"
   1fca8d0c2829e9760baec3cf83f3e8a4cc2c493b3c2b3d88ddf1164532058243
   

   Expected: down removes the container and the network, and the anonymous volume is still listed, attached to nothing. The last command removes this one test orphan.

4. Tear down with rm -fsv, then down.

   $ docker compose -p anonvol up -d
    Network anonvol_default Creating
    Network anonvol_default Creating
    Network anonvol_default Created
    Network anonvol_default Created
    Container anonvol-app-1 Creating
    Container anonvol-app-1 Created
    Container anonvol-app-1 Starting
    Container anonvol-app-1 Started
   $ A=$(docker inspect -f '{{range .Mounts}}{{if eq .Destination "/anon"}}{{.Name}}{{end}}{{end}}' anonvol-app-1)
   $ docker compose -p anonvol rm -fsv
    Container anonvol-app-1 Stopping
    Container anonvol-app-1 Stopped
   Going to remove anonvol-app-1
    Container anonvol-app-1 Removing
    Container anonvol-app-1 Removed
   $ docker compose -p anonvol down
    Network anonvol_default Removing
    Network anonvol_default Removed
   $ docker volume inspect "$A"
   []
   Error response from daemon: get b33ec27afc546708492a31254fa7d883af806e900858dacf4a3fd9f308186064: no such volume
   $ docker volume ls --filter name=anonvol_named
   DRIVER    VOLUME NAME
   local     anonvol_named
   

   Expected: no such volume for the anonymous one, anonvol_named still listed. rm removes only stopped service containers, so -s stops them first; -f skips the confirmation prompt (the Going to remove line still prints); -v removes the anonymous volumes attached to them. down then removes the network. If rm prints No stopped containers instead: Failure modes, row 2.

5. Find every teardown in your script. The leaking pattern is a plain down at the end of the run plus the same down in the EXIT trap. To follow along on the test stack, save this stand-in as bench.sh in anonvol/:

   #!/usr/bin/env bash
   # The leaking pattern: plain `down` at the end of the run AND in the EXIT trap.
   set -euo pipefail
   P=anonvol
   trap 'docker compose -p "$P" down' EXIT
   
   docker compose -p "$P" up -d
   echo "anonymous volume this run: $(docker inspect -f '{{range .Mounts}}{{if eq .Destination "/anon"}}{{.Name}}{{end}}{{end}}' "$P-app-1")"
   sh -c "${BENCH:-echo benchmark ran}"   # stand-in for the real benchmark
   docker compose -p "$P" down
   

   Then back it up, list its teardown lines and run it twice (the runs are cut to the relevant lines):

   $ chmod +x bench.sh
   $ cp bench.sh bench.sh.bak
   $ grep -nE 'trap|compose .*(down|rm)' bench.sh
   2:# The leaking pattern: plain `down` at the end of the run AND in the EXIT trap.
   5:trap 'docker compose -p "$P" down' EXIT
   10:docker compose -p "$P" down
   $ ./bench.sh; echo "exit status $?"
   …
   anonymous volume this run: a1ab691293e32a68e43b2a1e3b829decb16236b09634ebb68e4ab4cbdf36bec2
   benchmark ran
   …
   exit status 0
   $ ./bench.sh; echo "exit status $?"
   …
   anonymous volume this run: 50f304513f423d0d22988e94ec107b7d0a3debde0c4b34585fec763e06c95597
   benchmark ran
   …
   exit status 0
   $ docker volume ls --filter dangling=true --filter name=a1ab691293e32a68e43b2a1e3b829decb16236b09634ebb68e4ab4cbdf36bec2 --filter name=50f304513f423d0d22988e94ec107b7d0a3debde0c4b34585fec763e06c95597
   DRIVER    VOLUME NAME
   local     50f304513f423d0d22988e94ec107b7d0a3debde0c4b34585fec763e06c95597
   local     a1ab691293e32a68e43b2a1e3b829decb16236b09634ebb68e4ab4cbdf36bec2
   $ docker volume rm a1ab691293e32a68e43b2a1e3b829decb16236b09634ebb68e4ab4cbdf36bec2 50f304513f423d0d22988e94ec107b7d0a3debde0c4b34585fec763e06c95597
   a1ab691293e32a68e43b2a1e3b829decb16236b09634ebb68e4ab4cbdf36bec2
   50f304513f423d0d22988e94ec107b7d0a3debde0c4b34585fec763e06c95597
   

   Expected: grep shows every line that tears the stack down (here line 10 and the trap on line 5); two runs leave two dangling anonymous volumes, one per run. In each run the trap's down came second, found nothing left and logged a warning ending in Warning: No resource found to remove for project \"anonvol\". The last command removes the two test orphans. Run the same grep on <SCRIPT>.

6. Replace the teardown with one trap that runs rm -fsv, then down, both with -p. The fixed stand-in, saved over bench.sh:

   #!/usr/bin/env bash
   # Stand-in for a benchmark script: bring the stack up, run, always tear down.
   set -euo pipefail
   P=anonvol
   
   cleanup() {
     docker compose -p "$P" rm -fsv   # stop + remove containers AND their anonymous volumes
     docker compose -p "$P" down      # then the network; named volumes stay
   }
   trap cleanup EXIT
   
   docker compose -p "$P" up -d
   echo "anonymous volume this run: $(docker inspect -f '{{range .Mounts}}{{if eq .Destination "/anon"}}{{.Name}}{{end}}{{end}}' "$P-app-1")"
   sh -c "${BENCH:-echo benchmark ran}"   # stand-in for the real benchmark
   

   $ grep -nE 'trap|compose .*(down|rm)' bench.sh
   7:  docker compose -p "$P" rm -fsv   # stop + remove containers AND their anonymous volumes
   8:  docker compose -p "$P" down      # then the network; named volumes stay
   10:trap cleanup EXIT
   

   Expected: no down outside cleanup, and rm -fsv before down. In <SCRIPT>, give both commands the -p <PROJECT> its up uses and no -f: the trap may run in another directory, where a relative -f path or a missing -p makes Compose look for a compose file that is not there (Failure modes, rows 3 and 4). With -p alone, rm and down worked from an empty directory. The trap line comes before up, so a failing up ends the script through the trap like the failing benchmark in Verify. Under set -e, a command that fails inside cleanup ends it too, so a failed rm also skips down.

7. Run the fixed script.

   $ ./bench.sh; echo "exit status $?"
    Network anonvol_default Creating
    Network anonvol_default Creating
    Network anonvol_default Created
    Network anonvol_default Created
    Container anonvol-app-1 Creating
    Container anonvol-app-1 Created
    Container anonvol-app-1 Starting
    Container anonvol-app-1 Started
   anonymous volume this run: e13ed1d5f741e54e85914e40ba8db2d8a520350c2bd6735e16e4f0de839c7ade
   benchmark ran
    Container anonvol-app-1 Stopping
    Container anonvol-app-1 Stopped
   Going to remove anonvol-app-1
    Container anonvol-app-1 Removing
    Container anonvol-app-1 Removed
    Network anonvol_default Removing
    Network anonvol_default Removed
   exit status 0
   $ docker volume inspect e13ed1d5f741e54e85914e40ba8db2d8a520350c2bd6735e16e4f0de839c7ade
   []
   Error response from daemon: get e13ed1d5f741e54e85914e40ba8db2d8a520350c2bd6735e16e4f0de839c7ade: no such volume
   $ docker volume ls --filter name=anonvol_named
   DRIVER    VOLUME NAME
   local     anonvol_named
   

   Expected: Going to remove and Removed from the trap, exit status 0, no such volume for this run's anonymous volume, the named volume still there.