Docker Compose: 'volume ... already exists but was not created by Docker Compose ...'

volume "fix10-cs-q3_appdata" already exists but was not created by Docker Compose. Use `external: true` to use an existing volume — a volume with the exact name Compose wanted for the project's appdata volume already existed, made with docker volume create. Declare it as external to keep using it, or remove it if it holds nothing you need.

The warning did not stop anything: the container started and listed a file that had been put into the hand-made volume beforehand. The choice that matters is what down -v should do with the volume later.

The error

It is a warning, and up exited with code 0. The capture:

PS> docker volume create fix10-cs-q3_appdata
fix10-cs-q3_appdata
PS> docker compose -p fix10-cs-q3 up
time="2026-11-13T11:04:11+05:30" level=warning msg="volume \"fix10-cs-q3_appdata\" already exists but was not created by Docker Compose. Use `external: true` to use an existing volume"
 Network fix10-cs-q3_default Creating
...
 Container fix10-cs-q3-web-1 Started
...

The file:

services:
  web:
    image: alpine
    command: ["sh", "-c", "ls /data"]
    volumes:
      - appdata:/data
volumes:
  appdata:

Why it happens

A volume declared as appdata: in project fix10-cs-q3 gets the name fix10-cs-q3_appdata on the engine; the run after the fix below shows Compose creating exactly that name. A volume of that name was already there, created by hand, so Compose warned. A second run showed that it mounted that volume: a file written into the hand-made volume by a separate container appeared in the service's ls /data.

PS> docker run --rm --name fix10-cs-q3-marker -v fix10-cs-q3_appdata:/data alpine sh -c "echo test > /data/marker.txt"
PS> docker compose -p fix10-cs-q3 up
...
web-1  | marker.txt
...

Because Compose did not create it, docker compose down -v left it behind:

PS> docker compose -p fix10-cs-q3 down -v
...
 Network fix10-cs-q3_default Removed
PS> docker volume ls --filter name=fix10-cs-q3 --format {{.Name}}
fix10-cs-q3_appdata

That is the reason to settle it either way: with data you want to keep, the volume should be marked external; with a stray empty volume, it should go.

The fix

To keep the volume, declare it external under its full name:

volumes:
  appdata:
    name: fix10-cs-q3_appdata
    external: true

Run as project fix10-cs-q3x, this printed no warning, and down -v left the volume in docker volume ls. To start clean instead, remove the hand-made volume and let Compose create it:

PS> docker volume rm fix10-cs-q3_appdata
fix10-cs-q3_appdata
PS> docker compose -p fix10-cs-q3 up
 Volume fix10-cs-q3_appdata Creating
...
 Volume fix10-cs-q3_appdata Created
...

No warning, and this time down -v printed Volume fix10-cs-q3_appdata Removed. Only remove a volume after checking it holds nothing you need. In the marker test, docker volume rm followed by docker volume create of the same name gave an empty volume:

PS> docker volume rm fix10-cs-q3_appdata
fix10-cs-q3_appdata
PS> docker volume create fix10-cs-q3_appdata
fix10-cs-q3_appdata
PS> docker run --rm --name fix10-cs-q3-check -v fix10-cs-q3_appdata:/data alpine ls -A /data
PS> docker volume rm fix10-cs-q3_appdata
fix10-cs-q3_appdata

ls -A printed nothing: marker.txt was gone with the old volume.

How it was reproduced

A volume created with docker volume create fix10-cs-q3_appdata, then a one-service alpine file with a named volume appdata started with docker compose -p fix10-cs-q3 up from Windows PowerShell 5.1; then the external declaration as project fix10-cs-q3x, and finally the volume removed and the first file started again; a second round put marker.txt into a new hand-made volume with an alpine container, ran the project, then removed and recreated the volume and listed it. Docker Compose v5.7.0, Docker Engine 29.9.3, Docker Desktop 4.99.0 on Windows (version 10.0.26300). The names with fix10-cs-q3 are this test's own; every project was removed with docker compose down -v and the volume is gone.

Frequently asked

What does 'volume already exists but was not created by Docker Compose' mean?

A volume with the name Compose wants for the project already exists and was made outside Compose. In this test Compose warned, mounted it and exited with code 0.

Does docker compose down -v delete a volume it did not create?

No. In this test the hand-made volume was still listed by docker volume ls after docker compose down -v. A volume Compose created itself was removed.

How do I use an existing volume in docker compose?

Declare it under volumes with name: set to its full name and external: true. In this test that removed the warning and kept the volume through down -v.

More decoded errors in the Fixes category. The same situation with a network is Docker Compose: network exists but was not created by compose.