docker-run

View documentation for the original command

$ tldr docker container run

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

-a, --attach LIST
    Attach to STDIN, STDOUT or STDERR

--add-host HOST:IP
    Add custom host-to-IP mapping

-c, --cpu-shares int
    CPU shares (relative weight)

--cap-add CAPABILITY
    Add Linux capabilities

--cap-drop CAPABILITY
    Drop Linux capabilities

-d, --detach
    Run container in background

--device DEVICE
    Add host device to container

--dns IP
    Set custom DNS servers

-e, --env KEY=VAL
    Set environment variables

--env-file FILE
    Read env vars from file

--entrypoint EXECUTABLE
    Override image's entrypoint

--group-add GROUP
    Add supplemental groups

-h, --hostname HOSTNAME
    Set container hostname

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

--ip IP
    Set container IP address

--ipc MODE
    IPC namespace mode

--label KEY=VAL
    Set metadata labels

-l, --log-driver DRIVER
    Logging driver

--mac-address MAC
    Set container MAC address

-m, --memory BYTES
    Set memory limit

--memory-swap BYTES
    Total memory limit (memory + swap)

--network NETWORK
    Connect to a network

-P, --publish-all
    Publish all exposed ports

-p, --publish PORTS
    Publish container ports to host

--privileged
    Give extended privileges (security risk)

--rm
    Automatically remove on exit

--restart POLICY
    Restart policy

-t, --tty
    Allocate a pseudo-TTY

-u, --user USER
    Run as specific user

-v, --volume SRC:DEST
    Bind mount a volume

-w, --workdir DIR
    Set working directory inside container

docker run is a core Docker CLI command that creates and starts a new container from a specified image, allowing execution of applications in isolated, portable environments. It combines docker create and docker start functionalities with extensive customization options.

Key use cases include local development, testing, CI/CD pipelines, and microservices deployment. By default, it runs the image's CMD in the foreground, but options enable detached mode (-d), interactive sessions (-it), port publishing (-p), volume mounts (-v), environment variables (-e), resource limits (-m, --cpus), networking (--network), and security controls (--user, --cap-drop).

Containers are ephemeral; use --rm for automatic cleanup on exit. Override entrypoints with --entrypoint, set hostnames (-h), or apply restart policies (--restart). Advanced features support GPU access (--gpus), userns remapping (--userns), and sysctls (--sysctl).

Requires a running Docker daemon. Ideal for reproducible builds, but monitor resource usage and security implications, especially with --privileged. Widely used since Docker's inception for containerization workflows.

Requires Docker daemon running and user in docker group or root. --privileged grants host-like access, posing security risks. Resource limits enforced by cgroup support. Detached containers need docker stop to halt.

docker run hello-world
Run demo image.

docker run -it --rm -p 8080:80 nginx
Interactive Nginx with port mapping, auto-remove.

docker run -d --name myapp -v /data:/app/data myimage
Detached app with volume mount.

0: Success.
1-125: Container CMD error.
126: CMD not executable.
127: CMD not found.
128+N: SIG{N} trapped.

Introduced in Docker 0.7 (2013), part of initial open-source release by dotCloud (now Docker Inc.). Evolved with Docker Engine 1.0 (2014), adding features like volumes, networks, and Swarm integration in later versions.

docker ps(1), docker images(1), docker start(1), docker exec(1), docker create(1), podman-run(1)