DOCKER-COMPOSE-RUN(1)

💅 NAME 💅

docker-compose-run — run a one-off command on a service, bestie ✨

---

🌸 SYNOPSIS 🌸

docker compose run [OPTIONS] SERVICE [COMMAND] [ARGS...]

---

🎀 DESCRIPTION 🎀

Okay so picture this: you need to run a one-time command against a service. Not a forever thing. Just a lil pop-in, do the thing, and dip. That's run. 👑

Like, this right here starts the web service and runs bash as its command:

$ docker compose run web bash

When you use run, your command starts in a new container with all the config from that service — volumes, links, all of it. But here's the tea, there are two big differences and you gotta know them:

Difference numero uno: the command you pass to run overrides whatever command is defined in the service config. So say your web service is set up to start with bash — well, docker compose run web python app.py is gonna override that and use python app.py instead. You're the main character now, not the config. 💅

Difference number two: docker compose run does not create any of the ports listed in the service configuration. None. Zero. This is on purpose — it stops port collisions with ports that are already open. If you do want the service's ports created and mapped to the host, you gotta say so with --service-ports:

$ docker compose run --service-ports web python manage.py shell

Or, if you'd rather, you can map ports by hand with --publish or -p, literally just like you would with docker run:

$ docker compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell

Now, if you start a service that's configured with links, run first checks whether the linked service is running — and if it's stopped, it starts it up. Once all the linked services are up, run executes the command you handed it. For example, you could run:

$ docker compose run db psql -h db -U docker

Which opens an interactive PostgreSQL shell for the linked db container. Obsessed. 🐘✨

But what if you do not want run to start those linked containers? Use the --no-deps flag, bestie:

$ docker compose run --no-deps web python manage.py shell

And if you want the container removed after it runs — while also overriding the container's restart policy — the --rm flag is your girl:

$ docker compose run --rm web python manage.py db upgrade

That runs a database upgrade script and removes the container when it's done running, even if a restart policy is specified in the service configuration. Clean up after yourself, it's giving responsible queen. 🧹💖

---

✨ OPTIONS ✨

• --build[=false] — build the image before starting the container 🏗️
• --cap-add= — add Linux capabilities
• --cap-drop= — drop Linux capabilities
• -d, --detach[=false] — run the container in the background and print the container ID
• --entrypoint="" — override the entrypoint of the image
• -e, --env=[] — set environment variables
• -h, --help[=false] — help for run
• -i, --interactive[=true] — keep STDIN open even if not attached
• -l, --label=[] — add or override a label
• --name="" — assign a name to the container
• -T, --no-TTY[=true] — disable pseudo-TTY allocation (default: auto-detected)
• --no-deps[=false] — don't start linked services
• -p, --publish=[] — publish a container's port(s) to the host
• --quiet-pull[=false] — pull without printing progress information
• --remove-orphans[=false] — remove containers for services not defined in the Compose file
• --rm[=false] — automatically remove the container when it exits
• -P, --service-ports[=false] — run command with all service's ports enabled and mapped to the host
• --use-aliases[=false] — use the service's network useAliases in the network(s) the container connects to
• -u, --user="" — run as the specified username or uid
• -v, --volume=[] — bind mount a volume
• -w, --workdir="" — working directory inside the container

---

🦋 OPTIONS INHERITED FROM PARENT COMMANDS 🦋

• --dry-run[=false] — execute command in dry run mode 🌈

---

💜 SEE ALSO 💜

• docker-compose(1)

---

okay that's the whole page, you ate that fr fr 🫶 This lil love letter comes from the docker-compose-run(1) manual, dated Mar 2025 — go forth and run something iconic, bestie 💖✨👑