Docker Run Command with Examples

The docker run command creates and starts a container from a Docker image, and it’s the primary way you launch any containerized application. You give it an image name plus options for ports, volumes, environment variables, and more, and it returns a running container (or a container ID if you run it detached). This article explains the command’s syntax, common options, and real-world examples so you can use it confidently.

What Is Docker Run?

Docker is a platform for developing, shipping, and running applications inside lightweight, isolated environments called containers. A container is a running instance of an image—a read-only template with the application code, runtime, libraries, and settings. The docker run command is how you turn that template into a live, working process.

When you run docker run, Docker does several things automatically: it checks if the image exists locally, pulls it from a registry (like Docker Hub) if not, creates a new container from that image, and starts it. If you don’t specify a command, it runs the image’s default command. The container runs as long as the main process inside it is alive; when that process exits, the container stops.

Basic Syntax and First Examples

The basic syntax is:

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Here are a few simple examples to get started:

• docker run hello-world – runs a tiny test image that prints a welcome message and exits.
• docker run -it ubuntu bash – starts an interactive Ubuntu container with a bash shell. The -it flags combine -i (interactive, keep STDIN open) and -t (allocate a pseudo-TTY).
• docker run -d nginx – runs the official Nginx web server in detached mode (background).
• docker run --rm alpine echo "Hello" – runs a command and automatically removes the container after it exits.

Notice that the image name comes before the command. Anything after the image name is passed as the command and arguments to the container’s entrypoint.

Common Options You’ll Use Daily

Most docker run commands include a handful of options. Here are the ones you’ll use most often, with examples.

• Detached mode (-d): runs the container in the background and prints the container ID. docker run -d nginx
• Publish ports (-p): maps a host port to a container port. Format is host:container. docker run -p 8080:80 nginx maps host port 8080 to container port 80.
• Environment variables (-e): sets environment variables inside the container. docker run -e MYSQL_ROOT_PASSWORD=secret mysql:8
• Mount volumes (-v): mounts a host directory or file into the container. docker run -v /host/data:/container/data nginx
• Name the container (--name): gives the container a readable name instead of a random one. docker run --name my-web -d nginx
• Restart policy (--restart): defines when the container should restart automatically. docker run --restart unless-stopped -d nginx
• Remove after exit (--rm): automatically cleans up the container filesystem when it stops. Useful for short-lived tasks.

How to Choose the Right Options

Choosing options depends on what your application needs. Ask yourself:

• Does it need to be reachable from outside? Use -p to publish ports.
• Does it need to store data that survives container restarts? Use a volume (-v) or a bind mount.
• Does it need configuration? Use -e for environment variables or mount a config file.
• Should it run in the background? Use -d.
• Do you need to interact with it? Use -it.
• Is it a one-off task? Use --rm to avoid clutter.

For example, to run a PostgreSQL database that you can access from your host and that keeps data in a named volume, you might use:

docker run -d --name my-postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -v pgdata:/var/lib/postgresql/data postgres:16

This starts a detached container named my-postgres, sets the password, exposes port 5432, and stores data in a volume called pgdata.

Common Problems and How to Fix Them

New users often hit a few predictable issues. Here’s how to resolve them.

• Image not found locally: Docker will try to pull it. If it fails, check the image name and tag. For example, docker run postgres pulls the default latest tag; use postgres:16 for a specific version.
• Port already in use: If you get Bind for 0.0.0.0:8080 failed: port is already allocated, change the host port (e.g., -p 8081:80) or stop the other container.
• Container exits immediately: Some images (like alpine) have no long-running process by default. Use -it to keep it alive or run a command like tail -f /dev/null.
• Permission denied: On Linux, you may need to add your user to the docker group or use sudo (though using sudo is not recommended for security).
• Environment variable not set: Make sure you use the correct variable name for the image. Check the image’s documentation on Docker Hub.

Comparing docker run with docker start and docker exec

It’s easy to confuse docker run with other container commands. Here’s a quick comparison:

• docker run creates a new container from an image and starts it. Use it when you want to launch a fresh instance.
• docker start starts an existing, stopped container. Use it after you’ve stopped a container and want to bring it back up.
• docker exec runs a command inside an already running container. Use it to get a shell or run a one-off command in a live container. For example, docker exec -it my-container bash.

So if you need a shell in a running Nginx container, you’d use docker exec -it my-nginx bash, not docker run.

Security and Best Practices

Running containers securely matters, especially in production. Keep these points in mind:

• Use official images or images from trusted sources. Check the image’s Dockerfile and maintainer.
• Don’t run containers as root unless necessary. Use the --user flag or a Dockerfile that creates a non-root user.
• Limit capabilities with --cap-drop and --cap-add. For example, docker run --cap-drop ALL --cap-add NET_BIND_SERVICE my-app.
• Use read-only root filesystems with --read-only to prevent writes to the container’s filesystem.
• Never put secrets in environment variables that are visible in docker inspect. Use Docker secrets or a dedicated secret manager.
• Set resource limits with --memory and --cpus to prevent a container from consuming all host resources.

Frequently Asked Questions

What’s the difference between docker run and docker start?

docker run creates a brand-new container from an image and starts it. docker start starts an existing container that was previously stopped. If you run docker run with the same image again, you get a new container with a new ID.

How do I keep a container running in the background?

Use the -d flag (detached mode). For example, docker run -d nginx. The container runs in the background, and Docker prints the container ID. You can check logs with docker logs <container-id>.

How do I pass multiple environment variables?

Use multiple -e flags. For example: docker run -e USER=admin -e PASS=secret myapp. You can also use --env-file to load variables from a file.

Why does my container exit immediately?

Most likely the image’s main process finishes quickly. For example, alpine has no default long-running process. Use -it to keep it interactive, or run a command that stays alive, like tail -f /dev/null.

How do I map multiple ports?

Use multiple -p flags. For example, docker run -p 8080:80 -p 443:443 nginx maps both host ports to the container’s ports.

Can I change the container’s name after creation?

No, the container name is fixed at creation. You can use docker rename to change it, but it’s easier to use --name when you run the container.

Related

• Io1 Initialization Failed: Causes and Fixes
• Fix Nginx Basic Auth 404 Not Found
• Best Carbonite Alternatives for Small Business Cloud Backup