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

DockerBEGINNERLOWUpdated Dec 6, 2025· 193 views

The 'Couldn't find env file' error in Docker Compose occurs when the env_file directive references a file that doesn't exist or can't be found. This is typically resolved by creating the missing .env file, correcting the file path, or removing the env_file directive if not needed.

Quick fix

Fixes ERROR: Couldn't find env file: .env

# 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
  1. Create the missing .env file
  2. Check the env_file path in docker-compose.yml
  3. Run docker-compose from the correct directory
  4. Remove the env_file directive if not needed
docker — error
# 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
ERROR: Couldn't find env file: .env

What this error means

The "Couldn't find env file" error indicates that Docker Compose is looking for an environment file that doesn't exist at the specified location. This commonly occurs when your `docker-compose.yml` contains an `env_file:` directive pointing to a file that hasn't been created yet. Docker Compose uses environment files to inject environment variables into containers at runtime. The `env_file:` directive in your Compose file tells Docker where to find these variables. When Docker Compose starts, it validates that all referenced files exist before attempting to create containers. This error is particularly common when: 1. Cloning a project that uses `.env` files but doesn't commit them to version control (for security reasons) 2. The `.env` file exists but is in a different directory than expected 3. There's a typo in the filename (like `.env.dev` vs `.env_dev`) 4. The file was accidentally deleted or not yet created Note that Docker Compose has two different concepts involving env files: - The `.env` file in the project root (used for variable substitution in the Compose file itself) - The `env_file:` directive (used to pass variables to containers) This error specifically relates to files referenced by the `env_file:` directive.

Typical symptoms

  • Running `docker-compose up` shows 'ERROR: Couldn't find env file: .env' or similar path
  • Docker Compose commands fail immediately without starting any containers
  • Error appears after cloning a repository that uses environment files
  • The error shows the full path to the expected .env file location
  • Running `docker-compose build` also fails with the same error
  • `docker-compose config` fails while trying to validate the configuration
  • CI/CD pipeline fails at the docker-compose step with env file error

Common causes

  1. The .env file doesn't exist and needs to be created (most common)
  2. The env_file path in docker-compose.yml points to a non-existent location
  3. Running docker-compose from a different directory than expected
  4. The .env file was not committed to version control (intentionally for security)
  5. Typo in the filename or path (spaces, wrong extension, case sensitivity)
  6. The file exists but has incorrect permissions preventing Docker from reading it
  7. Using env_file directive when you don't actually need environment variables

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

1Create the missing .env file

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

bash
# 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:

bash
cp .env.example .env

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

2Check the env_file path in docker-compose.yml

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

yaml
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:

bash
# Show the full resolved config (will fail but shows the path)
docker-compose config
3Run docker-compose from the correct directory

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

bash
# 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:

bash
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.

4Remove the env_file directive if not needed

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

Before:

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

After:

yaml
services:
  web:
    image: nginx

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

yaml
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.

5Check for filename typos and hidden characters

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

bash
# 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:

bash
# Rename to remove any issues
mv ".env.dev " .env.dev
6Fix file permissions

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

bash
# 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:

bash
# Check who owns the file
ls -la .env

# Change ownership if needed
sudo chown $USER:$USER .env
7Use conditional env_file loading (Docker Compose V2)

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

yaml
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:

bash
docker compose version

Advanced notes

### Understanding Docker Compose Environment Variable Loading

Docker Compose has three distinct mechanisms for environment variables, which can be confusing:

1. The `.env` file (Compose file substitution)
- Located in the same directory as docker-compose.yml
- Variables are used for substitution within the Compose file itself
- Example: image: ${REGISTRY}/myapp:${TAG}
- Override with: docker-compose --env-file ./other.env up

2. The `env_file:` directive (Container variables)
- Specified per-service in docker-compose.yml
- Variables are passed INTO the container at runtime
- Not available during Compose file parsing
- This is where the "Couldn't find env file" error originates

3. The `environment:` directive (Inline variables)
- Explicitly defined in the Compose file
- Can reference Compose file substitution variables
- Takes precedence over env_file values

### Order of Precedence

When the same variable is defined in multiple places, Docker Compose uses this precedence (highest to lowest):

1. Values set with docker-compose run -e VAR=value
2. Values in the environment: directive
3. Values in the env_file: directive
4. Values in the Dockerfile ENV instruction
5. Values from the shell environment

### Build vs Run Time

The env_file: directive is evaluated at different times depending on the command:

bash
# Evaluated immediately (will fail if missing)
docker-compose build
docker-compose up
docker-compose config

# Not evaluated
docker-compose images
docker-compose version

This is why docker-compose build fails even though env_file values are typically only needed at runtime. It's a known behavior that has been discussed in GitHub issues.

### CI/CD Best Practices

For CI/CD pipelines where .env files shouldn't be committed:

yaml
# .github/workflows/deploy.yml
steps:
  - name: Create .env file
    run: |
      cat > .env << EOF
      DATABASE_URL=${{ secrets.DATABASE_URL }}
      API_KEY=${{ secrets.API_KEY }}
      EOF

  - name: Deploy
    run: docker-compose up -d

Or use environment variables directly:

yaml
# docker-compose.yml for CI
services:
  app:
    image: myapp
    environment:
      - DATABASE_URL  # Will be read from the shell environment
      - API_KEY

### Security Note

Never commit .env files containing secrets to version control. Instead:

1. Add .env to .gitignore
2. Provide a .env.example with placeholder values
3. Document required variables in your README
4. Use secret management in production (Docker Secrets, Vault, etc.)

Frequently asked questions

What does "ERROR: Couldn't find env file: .env" mean?
The "Couldn't find env file" error indicates that Docker Compose is looking for an environment file that doesn't exist at the specified location. yml contains an env_file: directive pointing to a file that hasn't been created yet. Docker Compose uses environment files to inject environment variables into containers at runtime.
How do I fix "ERROR: Couldn't find env file: .env"?
The 'Couldn't find env file' error in Docker Compose occurs when the env_file directive references a file that doesn't exist or can't be found. This is typically resolved by creating the missing .env file, correcting the file path, or removing the env_file directive if not needed.
What causes "ERROR: Couldn't find env file: .env"?
The .env file doesn't exist and needs to be created (most common) The env_file path in docker-compose.yml points to a non-existent location Running docker-compose from a different directory than expected
Is the "ERROR: Couldn't find env file: .env" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading