How to fix ERROR: Couldn't find env file: .env in Docker

The simplest fix is to create the .env file that Docker Compose is looking for:

# Navigate to your project directory (where docker-compose.yml is)
cd /path/to/your/project

# Create an empty .env file
touch .env

# Or create it with some variables
cat > .env << 'EOF'
# Environment variables
DATABASE_URL=postgres://user:pass@localhost:5432/db
API_KEY=your-api-key
NODE_ENV=development
EOF

If your project has a .env.example or .env.sample file, copy it as a starting point:

cp .env.example .env

Then edit the .env file to add your actual values.

Verify that the env_file: path in your docker-compose.yml matches where your .env file actually is:

services:
  web:
    image: myapp
    env_file:
      - ./.env           # Relative to docker-compose.yml location
      - ./config/.env    # In a subdirectory
      - .env.local       # Same directory, different name

Common path issues:
- ./env vs ./.env (missing the dot prefix)
- .env.dev vs .env_dev (dot vs underscore)
- Paths are relative to the docker-compose.yml file, not your current directory

To verify what Docker Compose is looking for:

# Show the full resolved config (will fail but shows the path)
docker-compose config

Docker Compose resolves relative paths from the directory containing the docker-compose.yml file. Make sure you're running commands from the right location:

# Check your current directory
pwd

# List files to confirm docker-compose.yml and .env are present
ls -la

# If .env is in a parent directory, navigate there
cd /path/to/project

# Or specify the project directory explicitly
docker-compose --project-directory /path/to/project up

You can also use the --env-file flag to specify a different location:

docker-compose --env-file /path/to/.env up

Note: The --env-file flag is for the Compose file variable substitution, not for the env_file: directive in services.

If you don't actually need to pass environment variables from a file, remove the env_file: directive:

Before:

services:
  web:
    image: nginx
    env_file:
      - .env

After:

services:
  web:
    image: nginx

Alternatively, if you only need a few variables, use the environment: directive instead:

services:
  web:
    image: nginx
    environment:
      - NODE_ENV=production
      - API_URL=https://api.example.com

This approach avoids the need for a separate .env file entirely.

Environment file names are case-sensitive on Linux and may have hidden issues:

# List all files including hidden ones
ls -la

# Look for files starting with .env
ls -la .env*

# Check for hidden characters or spaces in filenames
ls -la | cat -A

Common filename issues:
- .env (trailing space)
- .ENV (uppercase on case-sensitive systems)
- .env.dev vs .env_dev
- Curly quotes copied from documentation

If you see unusual characters, rename the file:

# Rename to remove any issues
mv ".env.dev " .env.dev

If the file exists but Docker can't read it, check permissions:

# Check current permissions
ls -la .env

# Make the file readable
chmod 644 .env

# If running Docker as a different user, ensure that user can read it
# For Docker Desktop on Mac/Windows, this is usually not an issue

On Linux with rootless Docker, you may need to ensure the file is readable by the user running the Docker daemon:

# Check who owns the file
ls -la .env

# Change ownership if needed
sudo chown $USER:$USER .env

With Docker Compose V2, you can make env_file optional using the required: false attribute:

services:
  web:
    image: myapp
    env_file:
      - path: ./.env
        required: false    # Won't fail if file doesn't exist
      - path: ./.env.local
        required: false

This is useful when:
- You want to support optional local overrides
- The .env file is only needed in certain environments
- You're building an image that doesn't need env vars at build time

Note: This syntax requires Docker Compose V2.17.0 or later. Check your version:

docker compose version