[BUG] env_file variables not injected at runtime when using top-level include

[siva1024]

Description

When using the top-level include feature in Docker Compose, environment variables defined via env_file are not being injected into the container at runtime.

This issue is not related to variable interpolation during Compose file parsing. The Compose configuration loads successfully, and services start without errors, but variables defined in env_file are missing from the container environment.

The same service definition works as expected when used directly in a single Compose file (without include), which suggests the issue is specific to how env_file is handled in combination with include.

This behavior is unexpected, as env_file should apply at runtime regardless of how the Compose configuration is structured.

Steps To Reproduce

Directory structure:
├── .env
├── compose
│ └── compose.yaml
└── compose.yaml

compose.yaml:

include:
  - path: ./compose/compose.yaml
    env_file:
      - .env

compose/compose.yaml:

services:
  test:
    image: busybox
    command: sh -c "env | grep TEST_VAR && sleep 300"

.env

TEST_VAR=hello_world

Run the following commands:

docker compose up

Result:

The container starts successfully, but TEST_VAR is not present in the container environment.
The command env | grep TEST_VAR produces no output.

Compose Version

Docker Compose version v5.1.0

Docker Environment

Client:
 Version:    29.2.1
 Context:    desktop-linux
 Debug Mode: false
 Plugins:
  agent: create or run AI agents (Docker Inc.)
    Version:  v1.29.0
    Path:     /Users/master/.docker/cli-plugins/docker-agent
  ai: Docker AI Agent - Ask Gordon (Docker Inc.)
    Version:  v1.19.0
    Path:     /Users/master/.docker/cli-plugins/docker-ai
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.32.1-desktop.1
    Path:     /Users/master/.docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v5.1.0
    Path:     /Users/master/.docker/cli-plugins/docker-compose
  debug: Get a shell into any image or container (Docker Inc.)
    Version:  0.0.47
    Path:     /Users/master/.docker/cli-plugins/docker-debug
  desktop: Docker Desktop commands (Docker Inc.)
    Version:  v0.3.0
    Path:     /Users/master/.docker/cli-plugins/docker-desktop
  dhi: CLI for managing Docker Hardened Images (Docker Inc.)
    Version:  v0.0.1
    Path:     /Users/master/.docker/cli-plugins/docker-dhi
  extension: Manages Docker extensions (Docker Inc.)
    Version:  v0.2.31
    Path:     /Users/master/.docker/cli-plugins/docker-extension
  init: Creates Docker-related starter files for your project (Docker Inc.)
    Version:  v1.4.0
    Path:     /Users/master/.docker/cli-plugins/docker-init
  mcp: Docker MCP Plugin (Docker Inc.)
    Version:  v0.40.1
    Path:     /Users/master/.docker/cli-plugins/docker-mcp
  model: Docker Model Runner (Docker Inc.)
    Version:  v1.1.5
    Path:     /Users/master/.docker/cli-plugins/docker-model
  offload: Docker Offload (Docker Inc.)
    Version:  v0.5.70
    Path:     /Users/master/.docker/cli-plugins/docker-offload
  pass: Docker Pass Secrets Manager Plugin (beta) (Docker Inc.)
    Version:  v0.0.24
    Path:     /Users/master/.docker/cli-plugins/docker-pass
  sandbox: Docker Sandbox (Docker Inc.)
    Version:  v0.12.0
    Path:     /Users/master/.docker/cli-plugins/docker-sandbox
  sbom: View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc.)
    Version:  0.6.0
    Path:     /Users/master/.docker/cli-plugins/docker-sbom
  scout: Docker Scout (Docker Inc.)
    Version:  v1.20.1
    Path:     /Users/master/.docker/cli-plugins/docker-scout

Server:
 Containers: 3
  Running: 0
  Paused: 0
  Stopped: 3
 Images: 4
 Server Version: 29.2.1
 Storage Driver: overlayfs
  driver-type: io.containerd.snapshotter.v1
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 CDI spec directories:
  /etc/cdi
  /var/run/cdi
 Discovered Devices:
  cdi: docker.com/gpu=webgpu
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: dea7da592f5d1d2b7755e3a161be07f43fad8f75
 runc version: v1.3.4-0-gd6d73eb8
 init version: de40ad0
 Security Options:
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 6.12.76-linuxkit
 Operating System: Docker Desktop
 OSType: linux
 Architecture: aarch64
 CPUs: 10
 Total Memory: 7.653GiB
 Name: docker-desktop
 ID: 55dafb34-9718-4070-9ba2-2889a354e25d
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 HTTP Proxy: http.docker.internal:3128
 HTTPS Proxy: http.docker.internal:3128
 No Proxy: hubproxy.docker.internal
 Labels:
  com.docker.desktop.address=unix:///Users/master/Library/Containers/com.docker.docker/Data/docker-cli.sock
 Experimental: false
 Insecure Registries:
  hubproxy.docker.internal:5555
  ::1/128
  127.0.0.0/8
 Live Restore Enabled: false
 Firewall Backend: iptables

Anything else?

No response

[ndeloof]

With your reproduction example, TEST_VAR is not expected to be injected into container. env_file is only used to set variables used for interpolation or populate container if this one is configured to:

services:
  test:
    image: busybox
    environment:
        - TEST_VAR # set TEST_VAR in container from value set in user's env or .env file(s)
    command: sh -c "env | grep TEST_VAR && sleep 300"

the issue is still relevant with this additional setting in yaml.

I'm working on a major refactoring of the compose parsing that could help address this issue: compose-spec/compose-go#854

[siva1024]

Thanks for the clarification and for confirming that the issue is still relevant.

Explicitly listing variables under environment does make the setup work as expected, so that provides a usable workaround for now.

That said, this highlights a gap in expected behavior and documentation. It is not immediately obvious that:

• env_file does not automatically inject variables into the container when using top-level include
• variables must also be explicitly declared under environment to be passed into the container

This lack of implicit injection can lead to confusion and requires duplication as the number of variables grows.

Given that the issue is still relevant and a refactor is in progress, I’ll leave this open for now and can help retest once the changes from compose-spec/compose-go#854 are available.

In the meantime, clarifying this behavior in the documentation would help prevent similar confusion for others.

[ndeloof]

env_file does set container environment when set at service level
env_file in include directive applies to the parsing of the other compose.yaml file