Skip to main content
Creates a container from an image without starting it. This command accepts most of the same process/resource/management flags as container run, but leaves the container stopped after creation.

Usage

container create [<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 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)

Build docs developers (and LLMs) love