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.
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.
First, identify what project name Docker Compose is trying to use:
# 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.
The quickest fix is to specify a valid project name on the command line:
# 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 upImportant: You must use the same -p flag for all subsequent commands (logs, down, exec, etc.) to reference the same project.
For a persistent solution without modifying commands, set the environment variable:
# 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 -dFor a permanent solution, add it to your shell profile (~/.bashrc, ~/.zshrc) or create a .env file in your project directory:
# .env file in project root
COMPOSE_PROJECT_NAME=myprojectDocker Compose automatically reads .env files.
The cleanest long-term solution is to explicitly set the project name in your docker-compose.yml or compose.yaml:
name: myproject # Top-level, before 'services:'
services:
web:
image: nginx
db:
image: postgresNote: 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:
docker compose versionIf you control the directory name, rename it to be compliant:
# 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
# Rename directory
cd ..
mv "My.Project" "my-project"
cd my-project
docker compose upIf you have a .env file, check that COMPOSE_PROJECT_NAME contains a valid value:
# Check current .env
cat .env | grep COMPOSE_PROJECT_NAMEFix any invalid values:
# 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_v2Note: Docker Compose may silently fail if the .env file contains an invalid project name without showing a clear error message.
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:
# 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 -ddockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec