docker compose run: One-Off Service Commands

Start a fresh one-off container for a service - perfect for test commands.

docker compose run starts a new container for a service to run a one-off command, alongside its dependencies. This page covers --rm, --no-deps, and CI test patterns.

What it does

docker compose run creates a new container for a service (not the long-running one) to run a command, starting linked dependencies first. It is ideal for tests, migrations, and tasks. --rm cleans up the container afterward.

Common usage

Terminal

docker compose run --rm api npm test
docker compose run --rm --no-deps api ./lint
docker compose run -T --rm api ./migrate

Common errors in CI

Unlike up, run does not publish the service ports by default (use --service-ports if you need them). Without --rm, one-off containers accumulate on a runner - always pass --rm in CI. Like exec, run allocates a TTY; pass -T in non-interactive pipelines. The command exit code is the run exit code, so CI can gate on docker compose run --rm api npm test.

Related guides

docker compose exec: Run a Command in a ServiceHow docker compose exec works: running a command in a running service container, the -T flag for CI, and not-… docker compose up: Start Services & CI ErrorsHow docker compose up works: starting all services from a compose file, detached mode, --build, --wait, and t… docker run: Usage, Options & Common CI ErrorsHow docker run works: starting a container from an image, port and volume mapping, env vars, --rm cleanup, an… docker compose down: Tear Down a Compose StackHow docker compose down works: stopping and removing services, networks, and volumes, the -v flag, and clean…