[BUG] Multiple files in `compose.yml`'s `env-file` attribute does not work as `--env-file` option for interpolation

[pereira-sidnei-tp]

Description

The documentation about variable interpolation suggests the use of multiple --env-file will apply for interpolation purposes and it does.

However the same does not happen when using multiple files for env-file compose's service level attribute - it just sticks with default .env file. I understand interpolation has to happen to env-file itself can be parsed, but the fact that the attribute and the option has the same name it seems a little bit oddly behaviour.

Not sure it's an actual bug or intentional behavior - if so I think it deserves at least a disclaimer note on the mentioned documentation (couldn't find it anywhere).

Steps To Reproduce

1. have the following docker-compose.yml

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        LOCAL_UID: ${LOCAL_UID}
        LOCAL_GID: ${LOCAL_GID}
    container_name: company_eligibles_api
    image: company_eligibles_api
    env_file:
      - ./.env
      - ./.env.dev.build

2. and the following .env

SOME_ENV=some_value

3. and the following .env.dev.build

LOCAL_UID=1001
LOCAL_GID=1001

4. then run docker compose config --environment | grep "LOCAL_.ID" won't show any value despite warns about missing LOCAL_UID and LOCAL_GID
5. while running docker compose config --environment | grep "SOME_ENV" will (beyond the same warnings)
6. remove ./.env from within env_file then repeat 4..5: same result

Compose Version

Docker Compose version v2.39.4

Docker Environment

Client: Docker Engine - Community
 Version:    28.5.0
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.29.1
    Path:     /usr/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v2.39.4
    Path:     /usr/libexec/docker/cli-plugins/docker-compose

Server:
 Containers: 0
  Running: 0
  Paused: 0
  Stopped: 0
 Images: 17
 Server Version: 28.5.0
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: systemd
 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
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: b98a3aace656320842a23f4a392a33f46af97866
 runc version: v1.3.0-0-g4ca628d1
 init version: de40ad0
 Security Options:
  apparmor
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 7.0.0-15-generic
 Operating System: Ubuntu 26.04 LTS
 OSType: linux
 Architecture: x86_64
 CPUs: 14
 Total Memory: 30.05GiB
 Name: USCLNX2099
 ID: 7efa73f5-e0d6-4221-bdb9-f7a5144cd8da
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Experimental: false
 Insecure Registries:
  ::1/128
  127.0.0.0/8
 Live Restore Enabled: false

Anything else?

By the way, the use case I was trying to reach was make it to implicitly pass UID and GID from local host user to docker compose build since an .env.dev.build was previously filled if LOCAL_UID and LOCAL_GID, so I can use them within build to add application user with same IDs from host and so avoid permission issues while sharing my local codebase through volume with container for development.

• No need to export ENV from anywhere;
• no need to polute .env for such specific matter;
• no need to use --build-arg nor --env-file all the time.

I know there are other ways like just using docker compose --user $(id -u):$(id -g) [...] and deal with the "I have no name!@" case or even enable auto watch and don't use volumes at all, but I was exploring this path of action.

[ndeloof]

env_file in service declaration isn't involved in interpolation, it is only used to define container's environment. This is a direct equivalent for docker run --env-file ... flag.