Docker Compose — Project Name & Directory

2 minute read

Every Docker Compose stack has a project name. This name prefixes all resources Compose creates — containers, networks, and volumes. Understanding how it works prevents naming collisions and confusion.

What is the Project Name?

The project name is used as a prefix for everything Compose creates:

Project name: myapp

Resources created:
  Container: myapp-web-1
  Container: myapp-db-1
  Network:   myapp_default
  Volume:    myapp_pgdata

How Compose Determines the Project Name

Compose uses this priority order:

Priority Source Example
1 --project-name flag docker compose -p myapp up
2 COMPOSE_PROJECT_NAME env var export COMPOSE_PROJECT_NAME=myapp
3 name: in compose.yml name: myapp (top-level key)
4 Directory name /home/user/myapp/ → myapp

Default: Directory Name

The most common case — Compose uses the directory name:

# Project directory
pwd
# /home/user/awesome-project

docker compose up -d
# Resources prefixed with "awesome-project"

docker compose ps

NAME                          STATUS
awesome-project-web-1         running
awesome-project-db-1          running

Setting Project Name Explicitly

Option 1: Command-line flag

docker compose -p myapp up -d
docker compose -p myapp ps
docker compose -p myapp down

Important: When using -p, you must include it in every command, or Compose won’t find the running stack.

Option 2: Environment variable

export COMPOSE_PROJECT_NAME=myapp
docker compose up -d
docker compose ps   # Works without -p

Option 3: Top-level name: key

# compose.yml
name: myapp

services:
  web:
    image: nginx

This is the cleanest approach — the project name travels with the file.

Why Project Names Matter

Avoiding Collisions

If two projects use the same compose file structure in different directories:

/home/user/project-a/compose.yml  → project-a-web-1
/home/user/project-b/compose.yml  → project-b-web-1

Different directories = different project names = no collisions.

The Danger of Generic Names

# BAD — generic directory name
cd /tmp/test
docker compose up -d
# Creates: test-web-1, test-db-1

# Later, different project
cd /tmp/test2
# If you accidentally cd to /tmp/test first...
docker compose down  # OOPS — tears down the wrong stack!

Best practice: Use the name: key in your compose file or meaningful directory names.

Listing All Compose Projects

docker compose ls

NAME                STATUS              CONFIG FILES
myapp               running(2)          /home/user/myapp/compose.yml
blog                running(3)          /home/user/blog/compose.yml

Summary

Method Example Best For
Directory name cd myapp && docker compose up Default, simple projects
name: key name: myapp in compose.yml Explicit, portable
-p flag docker compose -p myapp up Quick override
Env var COMPOSE_PROJECT_NAME=myapp CI/CD pipelines

Quick Reference

Item Detail
Default project name Current directory name
Explicit name name: myapp in compose.yml
CLI override docker compose -p myapp up
Env var COMPOSE_PROJECT_NAME=myapp
List projects docker compose ls
Naming convention Container: project-service-number

You may also enjoy