Compose Clinic
Guias / Caminhos · 02

Caminhos · 02

Qual .env é lido quando você usa docker compose -f?

O caminho do arquivo de interpolação e o caminho do arquivo de ambiente do serviço não partem necessariamente da mesma pasta.

Modelo verificadoCompose 5.3.012 set 20266 min

O que medimos nesta versão

No Compose 5.3.0, nosso comando -f project/compose.yaml usou project/.env por padrão. O argumento --env-file cli.env foi relativo à pasta de execução. Já env_file: config/service.env foi relativo ao arquivo Compose.

Anote a versão ao investigar caminhos. Um tutorial antigo ou outra implementação pode não reproduzir exatamente este teste.

Monte esta estrutura

scratch/                 # execute os comandos aqui
  .env                   # CC_WHICH=caller
  cli.env                # CC_WHICH=explicit-caller-file
  project/
    .env                 # CC_WHICH=project
    compose.yaml
    config/
      service.env        # CC_SERVICE_PATH=relative-to-compose-file

Conteúdo do arquivo Compose:

services:
  probe:
    image: busybox:1.37
    env_file: config/service.env
    environment:
      CC_WHICH: ${CC_WHICH:-fallback}

Execute a partir de scratch/, sem uma variável CC_WHICH exportada no shell.

Compare os resultados

docker compose -f project/compose.yaml config

Resultado medido: CC_WHICH=project e CC_SERVICE_PATH=relative-to-compose-file.

docker compose --env-file cli.env -f project/compose.yaml config

Resultado medido: CC_WHICH=explicit-caller-file, mantendo o mesmo CC_SERVICE_PATH. Escolher outro arquivo de interpolação não mudou a localização do arquivo do serviço.

O caminho parecido que falha

docker compose --env-file config/service.env -f project/compose.yaml config

Não existe scratch/config/service.env. Nosso comando retornou erro com couldn’t find env file. O argumento de linha de comando não foi reinterpretado como um caminho dentro de project/.

Se você realmente quiser usar esse arquivo também como entrada do modelo, o caminho explícito a partir daqui seria project/config/service.env. Um arquivo separado para o modelo costuma deixar a intenção mais clara.

Deixe seu script reproduzível

  1. Registre docker compose version.
  2. Defina a pasta de execução do script.
  3. Escolha caminhos explícitos para o Compose e para o arquivo de interpolação.
  4. Confira o modelo antes de publicar qualquer mudança.

Um caminho absoluto para --env-file pode ajudar quando a pasta de execução varia. Este teste não cobre múltiplos arquivos Compose, redirecionamento por COMPOSE_FILE, alteração de --project-directory ou Swarm. Nenhum container ou serviço existente foi alterado.

Fontes e prova

Documentação consultada em 12.09.2026. Prova própria:

Continue a investigação