Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Compose does not see the $PWD variable in my volume path

Error- ${PWD}:/app mounts the wrong folder or nothing

Short answer

Compose fills ${PWD} from the environment of the shell that runs it, not from the shell's own idea of the current folder. Where PWD is not set there, the value is blank. Use a relative path such as ./data, which Compose resolves from the compose file's folder, or set the variable yourself.

  • Applies to Docker Compose 2, Docker Engine 27
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the values Compose will use for interpolation and the resolved file. If PWD is missing or blank there, that is the whole problem.

    docker compose config --environment | grep -i "^PWD"
    docker compose config
  2. 2Match what you see, then jump to its fix

    1. 1docker compose config shows an empty or broken volume source where ${PWD} was.PWD is not set in the environment Compose runs inFix
    2. 2The same blank substitution happens for any ${NAME} you use.You need a variable in the file but did not give it a value or defaultFix
    3. 3The path in compose.yaml is right, but the app inside the container sees no value.The variable is set in your shell but never reaches the containerFix

What does the error look like?

  • - ${PWD}:/app mounts the wrong folder or nothing
  • Compose warns that a variable is not set and substitutes an empty string

Cause 1 of 3

PWD is not set in the environment Compose runs in

1Check

Compose uses Bash-like interpolation and reads the variables from the shell environment and a .env file. When a variable has no value and no default, it warns and uses an empty string.

docker compose config --environment

2Fix

Stop depending on PWD. A relative host path starting with ./ is resolved from the compose file's directory, which is what you wanted.

services:
  app:
    volumes:
      - ./src:/app/src

3Verify

Resolve the file again and read the host path Compose printed.

docker compose config | grep -A3 volumes

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

You need a variable in the file but did not give it a value or default

1Check

A name with no value is replaced by an empty string unless you add a default or a required marker.

docker compose config --no-interpolate | grep -n '\${'

2Fix

Give it a default with ${NAME:-default}, or make a missing value stop the run with ${NAME:?message}. You can also put NAME=value in a .env file next to compose.yaml.

services:
  app:
    volumes:
      - ${DATA_DIR:-./data}:/var/lib/app
      - ${CONFIG_DIR:?CONFIG_DIR is not set}:/etc/app:ro

3Verify

Run config once with and once without the variable set.

DATA_DIR=/srv/data CONFIG_DIR=/srv/conf docker compose config
docker compose config

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The variable is set in your shell but never reaches the container

1Check

Shell variables do not enter a container by themselves. They only work when you interpolate them in the file or list the name under environment.

docker compose run --rm app env | sort

2Fix

Reference the variable in the environment section, either as a bare name or as NAME=${NAME}.

services:
  app:
    environment:
      - DEBUG
      - API_URL=${API_URL}

3Verify

Run the same env listing again.

DEBUG=1 API_URL=http://example.com docker compose run --rm app env | grep -E 'DEBUG|API_URL'

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Use relative paths beginning with ./ for bind mounts in compose files.
  • Give every ${VAR} a default or a required message, and keep the defaults in a committed .env.example.
  • Run docker compose config in CI so an empty substitution fails the build.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.