Skip to main content
Runs a container from an image. If a command is provided, it will execute inside the container; otherwise the image’s default command runs. By default the container runs in the foreground and stdin remains closed unless -i/--interactive is specified.

​
Usage

container run [<options>] <image> [<arguments> ...]

​
Arguments

​
image
string
required
Image name
​
arguments
string[]
Container init process arguments

​
Process options

​
-e, --env
string
Set environment variables (format: key=value)
​
--env-file
string
Read in a file of environment variables (key=value format, ignores # comments and blank lines)
​
--gid
number
Set the group ID for the process
​
-i, --interactive
boolean
Keep the standard input open even if not attached
​
-t, --tty
boolean
Open a TTY with the process
​
-u, --user
string
Set the user for the process (format: name|uid[:gid])
​
--uid
number
Set the user ID for the process
​
-w, --workdir, --cwd
string
Set the initial working directory inside the container

​
Resource options

​
-c, --cpus
number
Number of CPUs to allocate to the container
​
-m, --memory
string
Amount of memory (1MiByte granularity), with optional K, M, G, T, or P suffix

​
Management options

​
-a, --arch
string
default:"arm64"
Set arch if image can target multiple architectures
​
--cidfile
string
Write the container ID to the path provided
​
-d, --detach
boolean
Run the container and detach from the process
​
--dns
string
DNS nameserver IP address
​
--dns-domain
string
Default DNS domain
​
--dns-option
string
DNS options
​
--dns-search
string
DNS search domains
​
--entrypoint
string
Override the entrypoint of the image
​
--init
boolean
Run an init process inside the container that forwards signals and reaps processes
​
--init-image
string
Use a custom init image instead of the default. This allows customizing boot-time behavior before the OCI container starts, such as running VM-level daemons, configuring eBPF filters, or debugging the init process.
​
-k, --kernel
string
Set a custom kernel path
​
-l, --label
string
Add a key=value label to the container
​
--mount
string
Add a mount to the container (format: type=<>,source=<>,target=<>,readonly)
​
--name
string
Use the specified name as the container ID
​
--network
string
Attach the container to a network
​
--no-dns
boolean
Do not configure DNS in the container
​
--os
string
default:"linux"
Set OS if image can target multiple operating systems
​
-p, --publish
string
Publish a port from container to host (format: [host-ip:]host-port:container-port[/protocol])
​
--platform
string
Platform for the image if it’s multi-platform. This takes precedence over —os and —arch
​
--publish-socket
string
Publish a socket from container to host (format: host_path:container_path)
​
--read-only
boolean
Mount the container’s root filesystem as read-only
​
--rm, --remove
boolean
Remove the container after it stops
​
--rosetta
boolean
Enable Rosetta in the container
​
--runtime
string
default:"container-runtime-linux"
Set the runtime handler for the container
​
--ssh
boolean
Forward SSH agent socket to container
​
--tmpfs
string
Add a tmpfs mount to the container at the given path
​
-v, --volume
string
Bind mount a volume into the container
​
--virtualization
boolean
Expose virtualization capabilities to the container (requires host and guest support)

​
Registry options

​
--scheme
string
default:"auto"
Scheme to use when connecting to the container registry. One of (http, https, auto)Behavior of autoWhen auto is selected, the target registry is considered internal/local if the registry host matches any of these criteria:
  • The host is a loopback address (e.g., localhost, 127.*)
  • The host is within the RFC1918 private IP ranges:
    • 10.*.*.*
    • 192.168.*.*
    • 172.16.*.* through 172.31.*.*
  • The host ends with the machine’s default container DNS domain
For internal/local registries, the client uses HTTP. Otherwise, it uses HTTPS.

​
Progress options

​
--progress
string
default:"ansi"
Progress type (format: none|ansi)

​
Examples

# run a container and attach an interactive shell
container run -it ubuntu:latest /bin/bash

# run a background web server
container run -d --name web -p 8080:80 nginx:latest

# set environment variables and limit resources
container run -e NODE_ENV=production --cpus 2 --memory 1G node:18

# run a container with a specific MAC address
container run --network default,mac=02:42:ac:11:00:02 ubuntu:latest

# run a container with an init process to reap zombies and forward signals
container run --init ubuntu:latest my-app

# run a container with a custom init image for boot customization
container run --init-image local/custom-init:latest ubuntu:latest

Build docs developers (and LLMs) love

Get started for freeTalk to us