How to fix ERROR: Invalid project name in Docker

DockerBEGINNERLOWUpdated Dec 1, 2025· 212 views

This error occurs when your Docker Compose project name contains invalid characters. Project names must contain only lowercase letters, numbers, dashes, and underscores, and must start with a letter or number. The fix is to rename your directory or explicitly set a valid project name.

Quick fix

Fixes ERROR: Invalid project name

# View the effective configuration including project name
docker compose config

# Or check your directory name
pwd
basename "$(pwd)"
  1. Check the current project name
  2. Set a valid project name with the -p flag
  3. Set COMPOSE_PROJECT_NAME environment variable
  4. Add a name: field to your compose file
docker — error
# View the effective configuration including project name
docker compose config
# Or check your directory name
pwd
basename "$(pwd)"
ERROR: Invalid project name

What this error means

Docker Compose uses a "project name" to isolate environments and name resources like containers, networks, and volumes. By default, this project name comes from the directory containing your `docker-compose.yml` file. The "Invalid project name" error appears when this name violates Docker Compose's naming rules: - **Allowed characters**: lowercase letters (a-z), numbers (0-9), dashes (-), and underscores (_) - **Must start with**: a lowercase letter or number - **Not allowed**: uppercase letters, dots (.), spaces, or special characters For example, if your project folder is named `My.Project`, `MyApp`, or `project@v2`, Docker Compose will reject it because it contains uppercase letters, dots, or special characters. This validation became stricter in Docker Compose v2.6.0 and later versions. Names that worked in older versions may now fail, particularly those with uppercase letters or dots.

Typical symptoms

  • Running "docker-compose up" shows "Invalid project name" error
  • Error message states the name "is not a valid project name"
  • Error indicates name must contain only characters from [a-z0-9_-]
  • Commands that worked before suddenly fail after upgrading Docker Compose
  • Projects in directories with uppercase letters or dots stop working
  • CI/CD pipelines fail with project name validation errors

Common causes

  1. Directory name contains uppercase letters (e.g., MyProject)
  2. Directory name contains dots (e.g., my.project or project.local)
  3. Directory name contains spaces or special characters
  4. Directory name starts with a dash or underscore
  5. COMPOSE_PROJECT_NAME environment variable set to an invalid value
  6. top-level 'name:' in compose file contains invalid characters
  7. Upgraded from Docker Compose v1 or v2.5.x where validation was less strict
  8. Using a single-letter directory name (edge case bug in some versions)

How to fix "ERROR: Invalid project name"

1Check the current project name

First, identify what project name Docker Compose is trying to use:

bash
# View the effective configuration including project name
docker compose config

# Or check your directory name
pwd
basename "$(pwd)"

The project name typically matches your folder name. If your folder is My.Project, that's the invalid name.

2Set a valid project name with the -p flag

The quickest fix is to specify a valid project name on the command line:

bash
# Use -p or --project-name to override the default
docker compose -p myproject up -d
docker compose -p myproject logs
docker compose -p myproject down

# Valid names: lowercase letters, numbers, dashes, underscores
docker compose -p my-app up
docker compose -p webapp_v2 up
docker compose -p app123 up

Important: You must use the same -p flag for all subsequent commands (logs, down, exec, etc.) to reference the same project.

3Set COMPOSE_PROJECT_NAME environment variable

For a persistent solution without modifying commands, set the environment variable:

bash
# Set for current session
export COMPOSE_PROJECT_NAME=myproject
docker compose up -d

# Or set inline for a single command
COMPOSE_PROJECT_NAME=myproject docker compose up -d

For a permanent solution, add it to your shell profile (~/.bashrc, ~/.zshrc) or create a .env file in your project directory:

bash
# .env file in project root
COMPOSE_PROJECT_NAME=myproject

Docker Compose automatically reads .env files.

4Add a name: field to your compose file

The cleanest long-term solution is to explicitly set the project name in your docker-compose.yml or compose.yaml:

yaml
name: myproject  # Top-level, before 'services:'

services:
  web:
    image: nginx
  db:
    image: postgres

Note: The top-level name: property requires Docker Compose v2.3.3 or later. If you get an error about name being invalid, you're using an older version.

Check your version:

bash
docker compose version
5Rename your project directory

If you control the directory name, rename it to be compliant:

bash
# Before: invalid names
My.Project/
MyApp/
project@v2/

# After: valid names
my-project/
myapp/
project-v2/

Rules for valid names:
- Use only: a-z, 0-9, -, _
- Start with a letter or number (not - or _)
- All lowercase

bash
# Rename directory
cd ..
mv "My.Project" "my-project"
cd my-project
docker compose up
6Fix invalid COMPOSE_PROJECT_NAME in .env file

If you have a .env file, check that COMPOSE_PROJECT_NAME contains a valid value:

bash
# Check current .env
cat .env | grep COMPOSE_PROJECT_NAME

Fix any invalid values:

bash
# Invalid examples:
COMPOSE_PROJECT_NAME=My.Project    # dots and uppercase
COMPOSE_PROJECT_NAME=My App        # spaces and uppercase
COMPOSE_PROJECT_NAME=              # empty

# Valid examples:
COMPOSE_PROJECT_NAME=my-project
COMPOSE_PROJECT_NAME=myapp
COMPOSE_PROJECT_NAME=app_v2

Note: Docker Compose may silently fail if the .env file contains an invalid project name without showing a clear error message.

Advanced notes

Version history of project name validation:
- v2.5.x and earlier: Uppercase letters and dots were generally accepted
- v2.6.0: Stricter validation introduced; uppercase letters rejected
- v2.17.0: Dots (.) no longer allowed in project names
- v2.17.2: Improved error messages for invalid names

If you're upgrading from an older version and seeing new errors, this stricter validation is likely the cause.

Precedence order for project name (highest to lowest):
1. -p / --project-name command line flag
2. COMPOSE_PROJECT_NAME environment variable
3. Top-level name: in compose file
4. Base name of directory containing compose file
5. Base name of current directory (if no compose file specified)

Known issues:
- Single-letter directory names can cause empty project names in some versions
- Invalid project name in .env may not show a clear error (GitHub issue #10471)
- Some special characters in paths may cause unexpected behavior

Docker Compose v1 vs v2:
The standalone docker-compose (v1, Python-based) had different validation rules than docker compose (v2, Go-based). If migrating from v1 to v2, project names may need adjustment.

Working with existing containers:
If you change the project name, Docker Compose won't recognize containers created with the old name. You'll need to:

bash
# Remove old containers with the invalid name (may need to use docker directly)
docker rm -f old_container_name

# Start fresh with valid project name
docker compose -p validname up -d

Frequently asked questions

What does "ERROR: Invalid project name" mean?
Docker Compose uses a "project name" to isolate environments and name resources like containers, networks, and volumes. yml file. Project, MyApp, or project@v2, Docker Compose will reject it because it contains uppercase letters, dots, or special characters.
How do I fix "ERROR: Invalid project name"?
This error occurs when your Docker Compose project name contains invalid characters. Project names must contain only lowercase letters, numbers, dashes, and underscores, and must start with a letter or number. The fix is to rename your directory or explicitly set a valid project name.
What causes "ERROR: Invalid project name"?
Directory name contains uppercase letters (e.g., MyProject) Directory name contains dots (e.g., my.project or project.local) Directory name contains spaces or special characters
Is the "ERROR: Invalid project name" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading