Docker compose folder name caused me much trouble

I have been racking my brain wondering why my docker compose projects where stepping on eachother’s toes!

I would bring one down, and the other would recreate, and this was scary because the other container was a production database service container.

Then I realized they both had the same nested folder names!

site-services/persistance/prod/docker-compose.yml here
different-site-services/persistance/prod/docker-compose.yml here

Since they both had the directory name prod they were recreating eachother’s lifecycles and other unexpected behaviors!

I was trying to organize my project services with dev and prod, but these folder names were causing so much trouble. Until I finally realized I had to rename the project folder, and they stayed decoupled.

I hope this saves someone else time and pain

This is the relevant part of the documentation that indicates why you experienced what you experience: Change pre-defined environment variables

The docker compose documentation indicates that the project name is prefixed, and if no project name is defined, the fallback is to use the folder name instead.

You can either override by providing the project name using --project-name MYPROJECTX (=long form of -p MYPROJECTY) or by setting it as environment variable COMPOSE_PROJECT_NAME=MYPROJECTX or as config in an .env file:


The docker compose help mentions that the default is the direct name, if no alternate project name is provided:

  -p, --project-name NAME     Specify an alternate project name
                              (default: directory name)

You seem to have just missed it.

1 Like

Thanks so much! So I can keep my nested directory structure, but I just have to update my .env files to specify project name.

Apprecitate it

But I explicitly named my containers using container_name , they didn’t pickup the project folder automatically.
However I had a - net default bridge network that definitely picked up the folder name.

So prod_net would conflict with another project network prod_net

But even if I explicitly name my network

    name: my-special-network

Would this still cause interference because another project gets the project label com.docker.compose.project = prod ?

Networks and volumes with external names are unique entities on the docker engine, regardless in how many projects they are referenced . They allow reusing the same resources (as in same id’s) in different projects.

Container names are also unique on the docker engine, creating more than one container with the same container name creates a conflict.

I assume so far none of this comes as a surprise…

The com.docker.compose.project label is metadata used to identify what resources belong to a project. . If you have different folders with different compose files that use the same project, it will be a messy inconsistency . Compose will ask you if you want to remove orphaned containers, even though they belong to different folders, from docker compose perspective they are the same project.

1 Like

This is a real caveat, and has potential to really frustrate new users.
Thanks for giving clarity here, it helped a lot.

I hope others will benefit.