docker-container-run

Run command in a new container from a tagged image

$ docker [[run|container run]] [image:tag] [command]

$ docker [[run|container run]] [[-d|--detach]] [image] [command]

$ docker [[run|container run]] --rm [[-it|--interactive --tty]] [image] [command]

$ docker [[run|container run]] [[-e|--env]] '[variable]=[value]' [[-e|--env]] [variable] [image] [command]

$ docker [[run|container run]] [[-v|--volume]] /[path/to/host_path]:/[path/to/container_path] [image] [command]

$ docker [[run|container run]] [[-p|--publish]] [host_port]:[container_port] [image] [command]

$ docker [[run|container run]] --entrypoint [command] [image]

$ docker [[run|container run]] --network [network] [image]

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

-a, --attach=[]
    Attach to STDIN, STDOUT, or STDERR

-d, --detach
    Run container in background and print container ID

--entrypoint=""
    Override the default ENTRYPOINT of the image

-e, --env=[]
    Set environment variables

--env-file=[]
    Read in a file of environment variables

-i, --interactive
    Keep STDIN open even if not attached

--name=""
    Assign a name to the container

-p, --publish=[]
    Publish a container's port(s) to the host

--privileged
    Give extended privileges to this container

--rm
    Automatically remove the container when it exits

-t, --tty
    Allocate a pseudo-TTY

-u, --user=""
    Username or UID (format: <user>:<group>)

-v, --volume=[]
    Bind mount a volume

-w, --workdir=""
    Working directory inside the container

--memory, -m=""
    Memory limit

--cpus=""
    CPUs limit

--network=""
    Connect a container to a network

--restart=""
    Restart policy

-h, --help
    Help for run

--help=false
    Help for run

The docker container run command creates and starts a new container from a specified Docker image, executing a command within it. If the image is not present locally, Docker automatically pulls it from a registry like Docker Hub. It supports extensive options for customization, including detaching the container (-d), mounting volumes (-v), setting environment variables (-e), exposing ports (-p), limiting resources (--memory, --cpus), and running interactively (-it). By default, the container runs in the foreground, attaching to the terminal, and stops upon command exit unless --rm is used to auto-remove it. This command is fundamental for containerized workloads, enabling isolated, reproducible environments for applications, services, and development. It integrates with Docker's networking, storage, and security features, making it versatile for microservices, CI/CD pipelines, and testing.

Common use cases include quick testing with hello-world, interactive shells in base images like Ubuntu, or deploying long-running services with background execution. Errors like 'no such image' or port conflicts are common pitfalls, resolvable by pulling images or checking host ports.

Requires Docker daemon running and sufficient privileges (sudo or docker group). Privileged mode (--privileged) grants host-like access, posing security risks. Detached containers consume resources until stopped. Port publishing conflicts with host ports cause failures. Image pulls fail without internet or registry access.

docker container run hello-world
docker container run -it --rm ubuntu bash
docker container run -d -p 80:80 --name web nginx

0: Success
1-127: Command exit code
128+N: SIG{N} received by command
125: Docker daemon unavailable
126: Command not executable
127: Command not found

Introduced in Docker 1.0 (2014) as docker run; restructured under docker container run in Docker 1.13 (2017) for subcommand organization. Evolved with features like overlay networks (1.9), CPU/memory limits (1.0+), and rootless mode (20.10+). Maintained by Docker Inc./Moby project.

docker run(1), podman-run(1), ctr run(8), runc run(8)