Docker Compose in the wrong directory: How to check what your command will actually affect

A hastily typed Compose command can hit the wrong stack. I'll show you how to check which project you're addressing before restarting anything.

· Martin Ehrentraut · about 7 minutes · AI-assisted

You just want to restart one of the many containers in your homelab. So you switch to the folder that belongs to the service and type docker compose restart. Then something unexpected happens: a bunch of other containers restart too, even though you only meant one service. With docker compose down, that mistake would be more painful: the command stops and removes containers and cleans up the associated networks that aren't external. Volumes are kept unless you add -v.

This follows from the rules Docker Compose uses to select a configuration and a project. Before your next restart, it's worth checking what Compose has found.

A terminal in a child directory points along an orange path to the Compose file of a parent stack.
AI-generated conceptual illustration, not a screenshot.

What Compose does before running a command

For up, restart, or down, Compose needs to know which configuration and project you mean. Your current directory plays a part. Options and environment variables can override that selection, though:

  1. Which Compose files are loaded?
  2. What project name is used?
  3. Which services are affected?

Without -f or a file selection through COMPOSE_FILE, Compose checks the current directory first. The default names, in order of preference, are compose.yaml, compose.yml, docker-compose.yml, and docker-compose.yaml. If several exist in the same folder, Compose uses the first one in that order. If it finds none, it checks the parent directory and keeps going up to the root. The search stops at the first folder containing a matching file. An automatically detected override file, such as compose.override.yaml, may also be loaded from that folder. It adds to or overrides parts of the base configuration. Source: Docker Compose CLI documentation.

That's handy for projects whose Compose file lives above the current subdirectory. It becomes a trap when there's a compose.yml up there that you didn't mean to use.

The project name has its own order of precedence: -p wins over COMPOSE_PROJECT_NAME, followed by a top-level name: in the Compose file. With multiple files, the last name: takes precedence. Only when none of those is set does Compose use the project directory's name. That's normally the folder containing the Compose file, or the first file's folder when you use several. You can change it with --project-directory. The project name is used in automatically assigned container and network names. Docker explains the project naming rules in its documentation.

A file isn't a separate namespace: different Compose files can resolve to the same project name and address the same resources. Which services a command affects also depends on the loaded configuration, any service names you specify, and any enabled profiles. Profiles enable optional services. You can limit up and restart to particular services; dependencies may bring other services into scope. Without those restrictions, the command affects the project's services selected for that operation.

The first trap: searching upward

Here's an example that probably looks familiar in plenty of homelabs. Your setup has a structure like this:

~/containers/
├── compose.yml
├── webseite/
├── datenbank/
└── monitoring/

You only want to restart the service in datenbank/. But there's no Compose file with a default name in that folder. Instead, it's called something like datenbank-compose.yml. Further up the tree, there's a compose.yml for the entire stack. Without -f or COMPOSE_FILE, your docker compose restart from datenbank/ therefore selects that file and restarts the services selected through it. The same applies to docker compose down: it shuts down far more than you intended and removes the affected containers.

You can bypass this search by specifying the file explicitly.

The second trap: you changed the file, but nothing happens

The second source of confusion is restart itself. Say you're in the right directory and change an environment variable, a port, or a volume in compose.yml. Then you type docker compose restart because you want to "restart" the service. After the restart, your change hasn't taken effect.

That's correct behaviour too. restart only restarts the existing containers; it doesn't create them from the current file. With docker compose up -d, Compose applies changes to the container configuration and recreates affected containers as needed. The -d leaves them running in the background. Docker describes this in the Compose CLI reference for up.

  • Changed the file, replaced the image, or added a label: docker compose up -d.
  • Just restart the existing containers without changing their configuration: docker compose restart.

A new image under the same tag isn't necessarily downloaded in the process. You may need to pull it first; changes to your own build may need a rebuild.

A magnifying glass highlights a project folder and configuration file; orange connections lead to its associated services.
AI-generated conceptual illustration, not a screenshot.

Three commands that clear things up

Before running up, restart, or down, you can check the loaded configuration and the existing containers. Use the same options and environment variables that you'll use for the command that follows.

  1. Show the effective configuration:
    docker compose config

    This command merges the loaded files, substitutes variables, and shows the resolved configuration. You'll also find the project name in the output. It describes the configuration, not the actual state of the containers or a complete preview of down. An option lets you list the service names individually:

    docker compose config --services
  2. Show running projects:
    docker compose ls

    The output lists running projects with their names, Compose files, and status. It shows existing projects in the Docker daemon you're connected to, not the file selection for your next command. An unexpected file path is a reason to investigate, but it doesn't prove you're in the wrong working directory. Use docker compose ls --all to include projects with stopped containers.

  3. List the current project's containers:
    docker compose ps

    By default, this shows the selected project's running containers. Use docker compose ps --all to include stopped ones.

Pointing the command at the right file

For a non-default filename such as datenbank-compose.yml, specify the file explicitly. The following commands assume you're in ~/containers/:

docker compose -f datenbank/datenbank-compose.yml ps
docker compose -f datenbank/datenbank-compose.yml up -d

The -f flag replaces automatic file discovery and takes precedence over COMPOSE_FILE. The relative path in this example still depends on your current directory. An absolute path lets you specify the file unambiguously from anywhere. Multiple -f flags load files in the given order; later entries add to or override earlier ones. An automatically discovered override file isn't added when you select files explicitly.

You can also set a project name if two files would otherwise resolve to the same one:

docker compose -p webseite up -d

-p only sets the project name; you still need to select the appropriate Compose file. For an existing stack, use its previous name: a different name can create an additional project. Allowed characters are lowercase letters from a to z, digits, hyphens, and underscores. The name must start with a lowercase letter or a digit.

In environments with lots of services, it's also worth checking COMPOSE_FILE. This variable can specify one or more files, replacing the automatic search. Running env | grep COMPOSE_FILE shows whether it's exported in your shell. But Compose can also load it from a .env file, which that shell command won't pick up. Empty output therefore doesn't rule out an explicit file selection.

A quick rule for everyday use

Before any Compose command that changes or shuts something down:

  1. Be in the right directory or specify the file with -f.
  2. Use config to check the configuration and project name. Compare them with the projects from docker compose ls and the containers from ps.
  3. For configuration changes, use up -d, not restart.

How do you keep track of this in your setup?

Editorial review: 8 November 2026. The linked primary sources in the Docker documentation cover file lookup, project names and command behaviour. Images: AI-generated conceptual illustrations, not screenshots.