Run a One-Off Container With docker run

docker run is the command that turns an image into a running container. For a one-off job, such as a quick test of a command or a version check, you want the container to do its work, show you the answer and disappear. This page shows the options that make that happen, and the leftovers you get when you forget one.

The basic shape

docker run [options] IMAGE [command]

The image is required. The command is optional, and it replaces the image's default command. Here the image is alpine:3.24, a very small Linux, and the command is echo.

docker run --rm alpine:3.24 echo "hello from a container"

Unable to find image 'alpine:3.24' locally
Status: Downloaded newer image for alpine:3.24
hello from a container

Docker downloaded the image because it was not on your machine, started a container, ran echo, printed the text, and stopped the container because the command had finished. A container lives exactly as long as its main command. Run it again and the download lines are gone.

docker run --rm alpine:3.24 uname -s

Linux

That is Linux, on a Windows computer. Docker Desktop runs the containers on a Linux engine inside WSL 2.

Why --rm matters

Without --rm, a stopped container stays on disk until you delete it. Run one with a name and see.

docker run --name leftover-demo alpine:3.24 echo "I am done"
docker ps -a --filter name=leftover-demo --format "table {{.Names}}\t{{.Status}}"

I am done
NAMES           STATUS
leftover-demo   Exited (0) Less than a second ago

The container is not running, but it is still there. One a day does not hurt. Hundreds do, and the name is also taken, so running the same command again fails. Remove it by name.

docker run --name leftover-demo alpine:3.24 echo "again"
docker rm leftover-demo

docker: Error response from daemon: Conflict. The container name "/leftover-demo" is already in use by container "7494691fee289844601d520a9d099e4d65229927f1dec89f12a71db35ab7722d". You have to remove (or rename) that container to be able to reuse that name.

Run 'docker run --help' for more information
leftover-demo

Read the error: the name is already used by a stopped container, so remove the old one. docker rm prints the name it removed. Use --rm whenever you do not need the container afterwards.

Pass a setting in

Use -e to set an environment variable inside the container. printenv prints one variable, so you can see that the setting arrived.

docker run --rm -e GREETING=hello alpine:3.24 printenv GREETING

hello

Check that nothing is left

docker ps -a --filter name=leftover-demo --format "table {{.Names}}\t{{.Status}}"

NAMES     STATUS

Only the header is there, so nothing is left. docker ps -a lists stopped containers too, and plain docker ps lists only the running ones.

Related course: Docker for Beginners.