[β¬οΈ Download] [π Command reference] [βFAQs & Troubleshooting] [π Additional documents]
nerdctl
is a Docker-compatible CLI for containerd.
β
Same UI/UX as docker
β
Supports Docker Compose (nerdctl compose up
)
β [Optional] Supports rootless mode, without slirp overhead (bypass4netns)
β [Optional] Supports lazy-pulling (Stargz, Nydus, OverlayBD)
β [Optional] Supports encrypted images (ocicrypt)
β [Optional] Supports P2P image distribution (IPFS) (*1)
β [Optional] Supports container image signing and verifying (cosign)
nerdctl is a non-core sub-project of containerd.
*1: P2P image distribution (IPFS) is completely optional. Your host is NOT connected to any P2P network, unless you opt in to install and run IPFS daemon.
To run a container with the default bridge
CNI network (10.4.0.0/24):
# nerdctl run -it --rm alpine
To build an image using BuildKit:
# nerdctl build -t foo /some-dockerfile-directory
# nerdctl run -it --rm foo
To build and send output to a local directory using BuildKit:
# nerdctl build -o type=local,dest=. /some-dockerfile-directory
To run containers from docker-compose.yaml
:
# nerdctl compose -f ./examples/compose-wordpress/docker-compose.yaml up
See also ./examples/compose-wordpress
.
To list local Kubernetes containers:
# nerdctl --namespace k8s.io ps -a
To build an image for local Kubernetes without using registry:
# nerdctl --namespace k8s.io build -t foo /some-dockerfile-directory
# kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
name: foo
spec:
containers:
- name: foo
image: foo
imagePullPolicy: Never
EOF
To load an image archive (docker save
format or OCI format) into local Kubernetes:
# nerdctl --namespace k8s.io load < /path/to/image.tar
To launch rootless containerd:
$ containerd-rootless-setuptool.sh install
To run a container with rootless containerd:
$ nerdctl run -d -p 8080:80 --name nginx nginx:alpine
See ./docs/rootless.md
.
Binaries are available here: https://github.com/containerd/nerdctl/releases
In addition to containerd, the following components should be installed:
- CNI plugins: for using
nerdctl run
.- v1.1.0 or later is highly recommended. Older versions require extra CNI isolation plugin for isolating bridge networks (
nerdctl network create
).
- v1.1.0 or later is highly recommended. Older versions require extra CNI isolation plugin for isolating bridge networks (
- BuildKit (OPTIONAL): for using
nerdctl build
. BuildKit daemon (buildkitd
) needs to be running. See also the document about setting up BuildKit. - RootlessKit and slirp4netns (OPTIONAL): for Rootless mode
- RootlessKit needs to be v0.10.0 or later. v0.14.1 or later is recommended.
- slirp4netns needs to be v0.4.0 or later. v1.1.7 or later is recommended.
These dependencies are included in nerdctl-full-<VERSION>-<OS>-<ARCH>.tar.gz
, but not included in nerdctl-<VERSION>-<OS>-<ARCH>.tar.gz
.
On Linux systems you can install nerdctl via brew:
brew install nerdctl
This is currently not supported for macOS. The section below shows how to install on macOS using brew.
Lima project provides Linux virtual machines for macOS, with built-in integration for nerdctl.
$ brew install lima
$ limactl start
$ lima nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
See ./docs/freebsd.md
.
- Linux containers: Known to work on WSL2
- Windows containers: experimental support for Windows (see below for features that are currently known to work)
To run containerd and nerdctl inside Docker:
docker build -t nerdctl .
docker run -it --rm --privileged nerdctl
The goal of nerdctl
is to facilitate experimenting the cutting-edge features of containerd that are not present in Docker (see below).
Note that competing with Docker is not the goal of nerdctl
. Those cutting-edge features are expected to be eventually available in Docker as well.
Also, nerdctl
might be potentially useful for debugging Kubernetes clusters, but it is not the primary goal.
Major:
- On-demand image pulling (lazy-pulling) using Stargz/Nydus/OverlayBD Snapshotter:
nerdctl --snapshotter=stargz|nydus|overlaybd run IMAGE
. - Image encryption and decryption using ocicrypt (imgcrypt):
nerdctl image (encrypt|decrypt) SRC DST
- P2P image distribution using IPFS:
nerdctl run ipfs://CID
. P2P image distribution (IPFS) is completely optional. Your host is NOT connected to any P2P network, unless you opt in to install and run IPFS daemon. - Recursive read-only (RRO) bind-mount:
nerdctl run -v /mnt:/mnt:rro
(make children such as/mnt/usb
to be read-only, too). Requires kernel >= 5.12, and crun >= 1.4 or runc >= 1.1 (PR #3272). - Cosign integration:
nerdctl pull --verify=cosign
andnerdctl push --sign=cosign
, and in Compose - Accelerated rootless containers using bypass4netns:
nerdctl run --label nerdctl/bypass4netns=true
Minor:
- Namespacing:
nerdctl --namespace=<NS> ps
. (NOTE: All Kubernetes containers are in thek8s.io
containerd namespace regardless to Kubernetes namespaces) - Exporting Docker/OCI dual-format archives:
nerdctl save
. - Importing OCI archives as well as Docker archives:
nerdctl load
. - Specifying a non-image rootfs:
nerdctl run -it --rootfs <ROOTFS> /bin/sh
. The CLI syntax conforms to Podman convention. - Connecting a container to multiple networks at once:
nerdctl run --net foo --net bar
- Running FreeBSD jails.
- Better multi-platform support, e.g.,
nerdctl pull --all-platforms IMAGE
- Applying an (existing) AppArmor profile to rootless containers:
nerdctl run --security-opt apparmor=<PROFILE>
. Usesudo nerdctl apparmor load
to load thenerdctl-default
profile.
Trivial:
- Inspecting raw OCI config:
nerdctl container inspect --mode=native
.
-
ctr
: incompatible with Docker CLI, and not friendly to users. Notably,ctr
lacks the equivalents of the following nerdctl commands:nerdctl run -p <PORT>
nerdctl run --restart=always --net=bridge
nerdctl pull
with~/.docker/config.json
and credential helper binaries such asdocker-credential-ecr-login
nerdctl logs
nerdctl build
nerdctl compose up
-
crictl
: incompatible with Docker CLI, not friendly to users, and does not support non-CRI features -
k3c v0.2 (abandoned): needs an extra daemon, and does not support non-CRI features
-
Rancher Kim (nee k3c v0.3): needs Kubernetes, and only focuses on image management commands such as
kim build
andkim push
-
PouchContainer (abandoned?): needs an extra daemon
nerdctl is a containerd non-core sub-project, licensed under the Apache 2.0 license. As a containerd non-core sub-project, you will find the:
information in our containerd/project
repository.
Tips: You should make your Go toolchain newer than 1.17.
Run make && sudo make install
.
Using go install github.com/containerd/nerdctl/cmd/nerdctl
is possible, but unrecommended because it does not fill version strings printed in nerdctl version
Run go test -v ./pkg/...
Run go test -exec sudo -v ./cmd/nerdctl/...
after make && sudo make install
.
For testing rootless mode, -exec sudo
is not needed.
To run tests in a container:
docker build -t test-integration --target test-integration .
docker run -t --rm --privileged test-integration
Run go test -exec sudo -v ./cmd/nerdctl/... -args -test.target=docker
to ensure that the test suite is compatible with Docker.
Lots of commands and flags are currently missing. Pull requests are highly welcome.
Please certify your Developer Certificate of Origin (DCO), by signing off your commit with git commit -s
and with your real name.
π³ = Docker compatible
π€ = nerdctl specific
π¦ = Windows enabled
Unlisted docker
CLI flags are unimplemented yet in nerdctl
CLI.
It does not necessarily mean that the corresponding features are missing in containerd.
- Container management
- π³ π¦ nerdctl run
- π³ π¦ nerdctl exec
- π³ π¦ nerdctl create
- π³ nerdctl cp
- π³ π¦ nerdctl ps
- π³ π¦ nerdctl inspect
- π³ nerdctl logs
- π³ nerdctl port
- π³ nerdctl rm
- π³ nerdctl stop
- π³ nerdctl start
- π³ nerdctl restart
- π³ nerdctl update
- π³ nerdctl wait
- π³ nerdctl kill
- π³ nerdctl pause
- π³ nerdctl unpause
- π³ docker rename
- π³ nerdctl container prune
- Build
- Image management
- Registry
- Network management
- Volume management
- Namespace management
- AppArmor profile management
- Builder management
- System
- Stats
- Shell completion
- Compose
- π³ nerdctl compose
- π³ nerdctl compose up
- π³ nerdctl compose logs
- π³ nerdctl compose build
- π³ nerdctl compose down
- π³ nerdctl compose images
- π³ nerdctl compose stop
- π³ nerdctl compose ps
- π³ nerdctl compose pull
- π³ nerdctl compose push
- π³ nerdctl compose config
- π³ nerdctl compose kill
- π³ nerdctl compose restart
- π³ nerdctl compose rm
- π³ nerdctl compose run
- π³ nerdctl compose version
- IPFS management
- Global flags
- Unimplemented Docker commands
- Additional documents
Run a command in a new container.
Usage: nerdctl run [OPTIONS] IMAGE [COMMAND] [ARG...]
π€ ipfs://
prefix can be used for IMAGE
to pull it from IPFS. See /docs/ipfs.md
for details.
Basic flags:
- π³ π¦
-i, --interactive
: Keep STDIN open even if not attached" - π³ π¦
-t, --tty
: Allocate a pseudo-TTYβ οΈ WIP: currently-t
conflicts with-d
- π³ π¦
-d, --detach
: Run container in background and print container ID - π³
--restart=(no|always|on-failure|unless-stopped)
: Restart policy to apply when a container exits- Default: "no"
- always: Always restart the container if it stops.
- on-failure[:max-retries]: Restart only if the container exits with a non-zero exit status. Optionally, limit the number of times attempts to restart the container using the :max-retries option.
- unless-stopped: Always restart the container unless it is stopped.
- π³
--rm
: Automatically remove the container when it exits - π³
--pull=(always|missing|never)
: Pull image before running- Default: "missing"
- π³
--pid=(host|container:<container>)
: PID namespace to use - π³
--stop-signal
: Signal to stop a container (default "SIGTERM") - π³
--stop-timeout
: Timeout (in seconds) to stop a container
Platform flags:
- π³
--platform=(amd64|arm64|...)
: Set platform
Init process flags:
- π³
--init
: Run an init inside the container that forwards signals and reaps processes. - π€
--init-binary=<binary-name>
: The custom init binary to use. We suggest you use the tini binary which is used in Docker project to get the same behavior. Please make sure the binary exists in yourPATH
.- Default:
tini
- Default:
Network flags:
- π³
--net, --network=(bridge|host|none|container:<container>|<CNI>)
: Connect a container to a network.- Default: "bridge"
- 'container:<name|id>': reuse another container's network stack, container has to be precreated.
- π€ Unlike Docker, this flag can be specified multiple times (
--net foo --net bar
)
- π³
-p, --publish
: Publish a container's port(s) to the host - π³
--dns
: Set custom DNS servers - π³
--dns-search
: Set custom DNS search domains - π³
--dns-opt, --dns-option
: Set DNS options - π³
-h, --hostname
: Container host name - π³
--add-host
: Add a custom host-to-IP mapping (host:ip) - π³
--ip
: Specific static IP address(es) to use - π³
--mac-address
: Specific MAC address to use. Be aware that it does not check if manually specified MAC addresses are unique. Supports network typebridge
andmacvlan
Resource flags:
- π³
--cpus
: Number of CPUs - π³
--cpu-quota
: Limit the CPU CFS (Completely Fair Scheduler) quota - π³
--cpu-period
: Limit the CPU CFS (Completely Fair Scheduler) period - π³
--cpu-shares
: CPU shares (relative weight) - π³
--cpuset-cpus
: CPUs in which to allow execution (0-3, 0,1) - π³
--cpuset-mems
: Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems - π³
--memory
: Memory limit - π³
--memory-reservation
: Memory soft limit - π³
--memory-swap
: Swap limit equal to memory plus swap: '-1' to enable unlimited swap - π³
--memory-swappiness
: Tune container memory swappiness (0 to 100) (default -1) - π³
--kernel-memory
: Kernel memory limit (deprecated) - π³
--oom-kill-disable
: Disable OOM Killer - π³
--oom-score-adj
: Tune containerβs OOM preferences (-1000 to 1000) - π³
--pids-limit
: Tune container pids limit - π€
--cgroup-conf
: Configure cgroup v2 (key=value) - π³
--blkio-weight
: Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) - π³
--cgroupns=(host|private)
: Cgroup namespace to use- Default: "private" on cgroup v2 hosts, "host" on cgroup v1 hosts
- π³
--device
: Add a host device to the container
Intel RDT flags:
- π€
--rdt-class=CLASS
: Name of the RDT class (or CLOS) to associate the container wit
User flags:
- π³ π¦
-u, --user
: Username or UID (format: <name|uid>[:<group|gid>]) - π€
--umask
: Set the umask inside the container. Defaults to 0022. Corresponds to Podman CLI. - π³
--group-add
: Add additional groups to join
Security flags:
- π³
--security-opt seccomp=<PROFILE_JSON_FILE>
: specify custom seccomp profile - π³
--security-opt apparmor=<PROFILE>
: specify custom AppArmor profile - π³
--security-opt no-new-privileges
: disallow privilege escalation, e.g., setuid and file capabilities - π€
--security-opt privileged-without-host-devices
: Don't pass host devices to privileged containers - π³
--cap-add=<CAP>
: Add Linux capabilities - π³
--cap-drop=<CAP>
: Drop Linux capabilities - π³
--privileged
: Give extended privileges to this container
Runtime flags:
- π³
--runtime
: Runtime to use for this container, e.g. "crun", or "io.containerd.runsc.v1". - π³
--sysctl
: Sysctl options, e.g "net.ipv4.ip_forward=1"
Volume flags:
- π³ π¦
-v, --volume <SRC>:<DST>[:<OPT>]
: Bind mount a volume, e.g.,-v /mnt:/mnt:rro,rprivate
- π³ option
rw
: Read/Write (when writable) - π³ option
ro
: Non-recursive read-only - π€ option
rro
: Recursive read-only. Should be used in conjunction withrprivate
. e.g.,-v /mnt:/mnt:rro,rprivate
makes children such as/mnt/usb
to be read-only, too. Requires kernel >= 5.12, and crun >= 1.4 or runc >= 1.1 (PR #3272). With older runc,rro
just works asro
. - π³ option
shared
,slave
,private
: Non-recursive "shared" / "slave" / "private" propagation - π³ option
rshared
,rslave
,rprivate
: Recursive "shared" / "slave" / "private" propagation - π€ option
bind
: Not-recursively bind-mounted - π€ option
rbind
: Recursively bind-mounted
- π³ option
- π³
--tmpfs
: Mount a tmpfs directory, e.g.--tmpfs /tmp:size=64m,exec
. - π³
--mount
: Attach a filesystem mount to the container. Consists of multiple key-value pairs, separated by commas and each consisting of a<key>=<value>
tuple. e.g.,-- mount type=bind,source=/src,target=/app,bind-propagation=shared
.- π³
type
: Current supported mount types arebind
,volume
,tmpfs
. The defaul type will be set tovolume
if not specified. i.e.,--mount src=vol-1,dst=/app,readonly
equals--mount type=volum,src=vol-1,dst=/app,readonly
- Common Options:
- π³
src
,source
: Mount source spec for bind and volume. Mandatory for bind. - π³
dst
,destination
,target
: Mount destination spec. - π³
readonly
,ro
,rw
,rro
: Filesystem permissinos.
- π³
- Options specific to
bind
:- π³
bind-propagation
:shared
,slave
,private
,rshared
,rslave
, orrprivate
(default). - π³
bind-nonrecursive
:true
orfalse
(default). If set to true, submounts are not recursively bind-mounted. This option is useful for readonly bind mount. - unimplemented options:
consistency
- π³
- Options specific to
tmpfs
:- π³
tmpfs-size
: Size of the tmpfs mount in bytes. Unlimited by default. - π³
tmpfs-mode
: File mode of the tmpfs in octal. Defaults to1777
or world-writable.
- π³
- Options specific to
volume
:- unimplemented options:
volume-nocopy
,volume-label
,volume-driver
,volume-opt
- unimplemented options:
- π³
Rootfs flags:
- π³
--read-only
: Mount the container's root filesystem as read only - π€
--rootfs
: The first argument is not an image but the rootfs to the exploded container. Corresponds to Podman CLI.
Env flags:
- π³ π¦
--entrypoint
: Overwrite the default ENTRYPOINT of the image - π³ π¦
-w, --workdir
: Working directory inside the container - π³ π¦
-e, --env
: Set environment variables - π³ π¦
--env-file
: Set environment variables from file
Metadata flags:
- π³ π¦
--name
: Assign a name to the container - π³ π¦
-l, --label
: Set meta data on a container - π³ π¦
--label-file
: Read in a line delimited file of labels - π³ π¦
--cidfile
: Write the container ID to the file - π€
--pidfile
: file path to write the task's pid. The CLI syntax conforms to Podman convention.
Logging flags:
- π³
--log-driver=(json-file|journald|fluentd|syslog)
: Logging driver for the container (defaultjson-file
).- π³
--log-driver=json-file
: The logs are formatted as JSON. The default logging driver for nerdctl.- The
json-file
logging driver supports the following logging options:- π³
--log-opt=max-size=<MAX-SIZE>
: The maximum size of the log before it is rolled. A positive integer plus a modifier representing the unit of measure (k, m, or g). Defaults to unlimited. - π³
--log-opt=max-file=<MAX-FILE>
: The maximum number of log files that can be present. If rolling the logs creates excess files, the oldest file is removed. Only effective whenmax-size
is also set. A positive integer. Defaults to 1. - π€
--log-opt=log-path=<LOG-PATH>
: The log path where the logs are written. The path will be created if it does not exist. If the log file exists, the old file will be renamed to<LOG-PATH>.1
.- Default:
<data-root>/<containerd-socket-hash>/<namespace>/<container-id>/<container-id>-json.log
- Example:
/var/lib/nerdctl/1935db59/containers/default/<container-id>/<container-id>-json.log
- Default:
- π³
- The
- π³
--log-driver=journald
: Writes log messages tojournald
. Thejournald
daemon must be running on the host machine.- π³
--log-opt=tag=<TEMPLATE>
: Specify template to setSYSLOG_IDENTIFIER
value in journald logs.
- π³
- π³
--log-driver=fluentd
: Writes log messages tofluentd
. Thefluentd
daemon must be running on the host machine.- The
fluentd
logging driver supports the following logging options:- π³
--log-opt=fluentd-address=<ADDRESS>
: The address of thefluentd
daemon, tcp(default) and unix sockets are supported.. - π³
--log-opt=fluentd-async=<true|false>
: Enable async mode for fluentd. The default value is false. - π³
--log-opt=fluentd-buffer-limit=<LIMIT>
: The buffer limit for fluentd. If the buffer is full, the call to record logs will fail. The default is 8192. (https://github.com/fluent/fluent-logger-golang/tree/master#bufferlimit) - π³
--log-opt=fluentd-retry-wait=<1s|1ms>
: The time to wait before retrying to send logs to fluentd. The default value is 1s. - π³
--log-opt=fluentd-max-retries=<1>
: The maximum number of retries to send logs to fluentd. The default value is MaxInt32. - π³
--log-opt=fluentd-sub-second-precision=<true|false>
: Enable sub-second precision for fluentd. The default value is false. - π€
--log-opt=fluentd-async-reconnect-interval=<1s|1ms>
: The time to wait before retrying to reconnect to fluentd. The default value is 0s. - π€
--log-opt=fluentd-request-ack=<true|false>
: Enable request ack for fluentd. The default value is false.
- π³
- The
- π³
--log-driver=syslog
: Writes log messages tosyslog
. Thesyslog
daemon must be running on either the host machine or remote.- The
syslog
logging driver supports the following logging options:- π³
--log-opt=syslog-address=<ADDRESS>
: The address of an externalsyslog
server. The URI specifier may betcp|udp|tcp+tls]://host:port
,unix://path
, orunixgram://path
. If the transport istcp
,udp
, ortcp+tls
, the default port is514
. - π³
--log-opt=syslog-facility=<FACILITY>
: Thesyslog
facility to use. Can be the number or name for any valid syslog facility. See the syslog documentation. - π³
--log-opt=syslog-tls-ca-cert=<VALUE>
: The absolute path to the trust certificates signed by the CA. Ignored if the address protocol is nottcp+tls
. - π³
--log-opt=syslog-tls-cert=<VALUE>
: The absolute path to the TLS certificate file. Ignored if the address protocol is nottcp+tls
. - π³
--log-opt=syslog-tls-key=<VALUE>
:The absolute path to the TLS key file. Ignored if the address protocol is nottcp+tls
. - π³
--log-opt=syslog-tls-skip-verify=<VALUE>
: If set totrue
, TLS verification is skipped when connecting to the daemon. Ignored if the address protocol is nottcp+tls
. - π³
--log-opt=syslog-format=<VALUE>
: Thesyslog
message format to use. If not specified the local UNIX syslog format is used, without a specified hostname. Specifyrfc3164
for the RFC-3164 compatible format,rfc5424
for RFC-5424 compatible format, orrfc5424micro
for RFC-5424 compatible format with microsecond timestamp resolution. - π³
--log-opt=tag=<VALUE>
: A string that is appended to theAPP-NAME
in thesyslog
message. By default, nerdctl uses the first 12 characters of the container ID to tag log messages.
- π³
- The
- π€ Accepts a LogURI which is a containerd shim logger. A scheme must be specified for the URI. Example:
nerdctl run -d --log-driver binary:///usr/bin/ctr-journald-shim docker.io/library/hello-world:latest
. An implementation of shim logger can be found at (https://github.com/containerd/containerd/tree/dbef1d56d7ebc05bc4553d72c419ed5ce025b05d/runtime/v2#logging)
- π³
Shared memory flags:
- π³
--ipc
: IPC namespace to use - π³
--shm-size
: Size of/dev/shm
GPU flags:
- π³
--gpus
: GPU devices to add to the container ('all' to pass all GPUs). Please see also ./docs/gpu.md for details.
Ulimit flags:
- π³
--ulimit
: Set ulimit
Verify flags:
- π€
--verify
: Verify the image (none|cosign). Seedocs/cosign.md
for details. - π€
--cosign-key
: Path to the public key file, KMS, URI or Kubernetes Secret for--verify=cosign
Unimplemented docker run
flags:
--attach
, --blkio-weight-device
, --cgroup-parent
, --cpu-rt-*
, --detach-keys
, --device-*
,
--disable-content-trust
, --domainname
, --expose
, --health-*
, --ip6
, --isolation
, --no-healthcheck
,
--link*
, --mac-address
, --publish-all
, --sig-proxy
, --storage-opt
,
--userns
, --uts
, --volume-driver
, --volumes-from
Run a command in a running container.
Usage: nerdctl exec [OPTIONS] CONTAINER COMMAND [ARG...]
Flags:
- π³
-i, --interactive
: Keep STDIN open even if not attached - π³
-t, --tty
: Allocate a pseudo-TTYβ οΈ WIP: currently-t
conflicts with-d
- π³
-d, --detach
: Detached mode: run command in the background - π³
-w, --workdir
: Working directory inside the container - π³
-e, --env
: Set environment variables - π³
--env-file
: Set environment variables from file - π³
--privileged
: Give extended privileges to the command - π³
-u, --user
: Username or UID (format: <name|uid>[:<group|gid>])
Unimplemented docker exec
flags: --detach-keys
Create a new container.
Usage: nerdctl create [OPTIONS] IMAGE [COMMAND] [ARG...]
π€ ipfs://
prefix can be used for IMAGE
to pull it from IPFS. See /docs/ipfs.md
for details.
The nerdctl create
command similar to nerdctl run -d
except the container is never started. You can then use the nerdctl start <container_id>
command to start the container at any point.
Copy files/folders between a running container and the local filesystem
Usage:
nerdctl cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-
nerdctl cp [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH
nerdctl cp
is designed only for use with trusted, cooperating containers.
Using nerdctl cp
with untrusted or malicious containers is unsupported and may not provide protection against unexpected behavior.
Flags:
- π³
-L, --follow-link
Always follow symbol link in SRC_PATH.
Unimplemented docker cp
flags: --archive
List containers.
Usage: nerdctl ps [OPTIONS]
Flags:
- π³
-a, --all
: Show all containers (default shows just running) - π³
--no-trunc
: Don't truncate output - π³
-q, --quiet
: Only display container IDs - π³
-s, --size
: Display total file sizes - π³
--format
: Format the output using the given Go template- π³
--format=table
(default): Table - π³
--format='{{json .}}'
: JSON - π€
--format=wide
: Wide table - π€
--format=json
: Alias of--format='{{json .}}'
- π³
- π³
-n, --last
: Show n last created containers (includes all states) - π³
-l, --latest
: Show the latest created container (includes all states) - π³
-f, --filter
: Filter containers based on given conditions- π³
--filter id=<value>
: Container's ID. Both full ID and truncated ID are supported - π³
--filter name=<value>
: Container's name - π³
--filter label=<key>=<value>
: Arbitrary string either a key or a key-value pair - π³
--filter exited=<value>
: Container's exit code. Only work with--all
- π³
--filter status=<value>
: One ofcreated, running, paused, stopped, exited, pausing, unknown
. Note thatrestarting, removing, dead
are not supported and will be ignored - π³
--filter before/since=<ID/name>
: Filter containers created before or after a given ID or name - π³
--filter volume=<value>
: Filter by a given mounted volume or bind mount - π³
--filter network=<value>
: Filter by a given network
- π³
Following arguments for --filter
are not supported yet:
--filter ancestor=<value>
--filter publish/expose=<port/startport-endport>[/<proto>]
--filter health=<value>
--filter isolation=<value>
--filter is-task=<value>
Display detailed information on one or more containers.
Usage: nerdctl inspect [OPTIONS] NAME|ID [NAME|ID...]
Flags:
- π€
--mode=(dockercompat|native)
: Inspection mode. "native" produces more information. - π³
--format
: Format the output using the given Go template, e.g,{{json .}}
- π³
--type
: Return JSON for specified type
Unimplemented docker inspect
flags: --size
Fetch the logs of a container.
nerdctl run -d
are supported.
Usage: nerdctl logs [OPTIONS] CONTAINER
Flags:
- π³
--f, --follow
: Follow log output - π³
--since
: Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) - π³
--until
: Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) - π³
-t, --timestamps
: Show timestamps - π³
-n, --tail
: Number of lines to show from the end of the logs (default "all")
Unimplemented docker logs
flags: --details
List port mappings or a specific mapping for the container.
Usage: nerdctl port CONTAINER [PRIVATE_PORT[/PROTO]]
Remove one or more containers.
Usage: nerdctl rm [OPTIONS] CONTAINER [CONTAINER...]
Flags:
- π³
-f, --force
: Force the removal of a running|paused|unknown container (uses SIGKILL) - π³
-v, --volumes
: Remove anonymous volumes associated with the container
Unimplemented docker rm
flags: --link
Stop one or more running containers.
Usage: nerdctl stop [OPTIONS] CONTAINER [CONTAINER...]
Flags:
- π³
-t, --time=SECONDS
: Seconds to wait for stop before killing it (default "10")- Tips: If the init process in container is exited after receiving SIGTERM or exited before the time you specified, the container will be exited immediately
Start one or more running containers.
Usage: nerdctl start [OPTIONS] CONTAINER [CONTAINER...]
Flags:
- π³
-a, --attach
: Attach STDOUT/STDERR and forward signals
Unimplemented docker start
flags: --checkpoint
, --checkpoint-dir
, --detach-keys
, --interactive
Restart one or more running containers.
Usage: nerdctl restart [OPTIONS] CONTAINER [CONTAINER...]
Flags:
- π³
-t, --time=SECONDS
: Seconds to wait for stop before killing it (default "10")- Tips: If the init process in container is exited after receiving SIGTERM or exited before the time you specified, the container will be exited immediately
Update configuration of one or more containers.
Usage: nerdctl update [OPTIONS] CONTAINER [CONTAINER...]
- π³
--cpus
: Number of CPUs - π³
--cpu-quota
: Limit the CPU CFS (Completely Fair Scheduler) quota - π³
--cpu-period
: Limit the CPU CFS (Completely Fair Scheduler) period - π³
--cpu-shares
: CPU shares (relative weight) - π³
--cpuset-cpus
: CPUs in which to allow execution (0-3, 0,1) - π³
--cpuset-mems
: Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems - π³
--memory
: Memory limit - π³
--memory-reservation
: Memory soft limit - π³
--memory-swap
: Swap limit equal to memory plus swap: '-1' to enable unlimited swap - π³
--kernel-memory
: Kernel memory limit (deprecated) - π³
--pids-limit
: Tune container pids limit - π³
--blkio-weight
: Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)
Block until one or more containers stop, then print their exit codes.
Usage: nerdctl wait CONTAINER [CONTAINER...]
Kill one or more running containers.
Usage: nerdctl kill [OPTIONS] CONTAINER [CONTAINER...]
Flags:
- π³
-s, --signal
: Signal to send to the container (default: "KILL")
Pause all processes within one or more containers.
Usage: nerdctl pause CONTAINER [CONTAINER...]
Unpause all processes within one or more containers.
Usage: nerdctl unpause CONTAINER [CONTAINER...]
Rename a container.
Usage: nerdctl rename CONTAINER NEW_NAME
Remove all stopped containers.
Usage: nerdctl container prune [OPTIONS]
Flags:
- π³
-f, --force
: Do not prompt for confirmation.
Unimplemented docker container prune
flags: --filter
Build an image from a Dockerfile.
βΉοΈ Needs buildkitd to be running. See also the document about setting up nerdctl build
with BuildKit.
Usage: nerdctl build [OPTIONS] PATH
Flags:
- π€
--buildkit-host=<BUILDKIT_HOST>
: BuildKit address - π³
-t, --tag
: Name and optionally a tag in the 'name:tag' format - π³
-f, --file
: Name of the Dockerfile - π³
--target
: Set the target build stage to build - π³
--build-arg
: Set build-time variables - π³
--no-cache
: Do not use cache when building the image - π³
--output=OUTPUT
: Output destination (format: type=local,dest=path)- π³
type=local,dest=path/to/output-dir
: Local directory - π³
type=oci[,dest=path/to/output.tar]
: Docker/OCI dual-format tar ball (compatible withdocker buildx build
) - π³
type=docker[,dest=path/to/output.tar]
: Docker format tar ball (compatible withdocker buildx build
) - π³
type=tar[,dest=path/to/output.tar]
: Raw tar ball - π³
type=image,name=example.com/image,push=true
: Push to a registry (seebuildctl build
documentation)
- π³
- π³
--progress=(auto|plain|tty)
: Set type of progress output (auto, plain, tty). Use plain to show container output - π³
--secret
: Secret file to expose to the build: id=mysecret,src=/local/secret - π³
--ssh
: SSH agent socket or keys to expose to the build (format:default|<id>[=<socket>|<key>[,<key>]]
) - π³
-q, --quiet
: Suppress the build output and print image ID on success - π³
--cache-from=CACHE
: External cache sources (eg. user/app:cache, type=local,src=path/to/dir) (compatible withdocker buildx build
) - π³
--cache-to=CACHE
: Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) (compatible withdocker buildx build
) - π³
--platform=(amd64|arm64|...)
: Set target platform for build (compatible withdocker buildx build
) - π³
--iidfile=FILE
: Write the image ID to the file - π€
--ipfs
: Build image with pulling base images from IPFS. See./docs/ipfs.md
for details. - π³
--label
: Set metadata for an image
Unimplemented docker build
flags: --add-host
, --network
, --squash
Create a new image from a container's changes
Usage: nerdctl commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]
Flags:
- π³
-a, --author
: Author (e.g., "nerdctl contributor nerdctl-dev@example.com") - π³
-m, --message
: Commit message - π³
-c, --change
: Apply Dockerfile instruction to the created image (supported directives: [CMD, ENTRYPOINT]) - π³
-p, --pause
: Pause container during commit (default: true)
List images
Usage: nerdctl images [OPTIONS] [REPOSITORY[:TAG]]
Flags:
- π³
-a, --all
: Show all images (unimplemented) - π³
-q, --quiet
: Only show numeric IDs - π³
--no-trunc
: Don't truncate output - π³
--format
: Format the output using the given Go template- π³
--format=table
(default): Table - π³
--format='{{json .}}'
: JSON - π€
--format=wide
: Wide table - π€
--format=json
: Alias of--format='{{json .}}'
- π³
- π³
--digests
: Show digests (compatible with Docker, unlike ID) - π³
-f, --filter
: Filter the images. For now, only 'before=image:tag' and 'since=image:tag' is supported.- π³
--filter=before=<image:tag>
: Images created before given image (exclusive) - π³
--filter=since=<image:tag>
: Images created after given image (exclusive) - π³
--filter=label<key>=<value>
: Matches images based on the presence of a label alone or a label and a value - π€
--filter=reference=<image:tag>
: Filter images by reference (Matches both docker compatible wildcard pattern and regexp match)
- π³
- π€
--names
: Show image names
Following arguments for --filter
are not supported yet:
--filter=dangling=true
: Filter images by dangling
Pull an image from a registry.
Usage: nerdctl pull [OPTIONS] NAME[:TAG|@DIGEST]
π€ ipfs://
prefix can be used for NAME
to pull it from IPFS. See /docs/ipfs.md
for details.
Flags:
- π³
--platform=(amd64|arm64|...)
: Pull content for a specific platform- π€ Unlike Docker, this flag can be specified multiple times (
--platform=amd64 --platform=arm64
)
- π€ Unlike Docker, this flag can be specified multiple times (
- π€
--all-platforms
: Pull content for all platforms - π€
--unpack
: Unpack the image for the current single platform (auto/true/false) - π³
-q, --quiet
: Suppress verbose output - π€
--verify
: Verify the image (none|cosign). Seedocs/cosign.md
for details. - π€
--cosign-key
: Path to the public key file, KMS, URI or Kubernetes Secret for--verify=cosign
Unimplemented docker pull
flags: --all-tags
, --disable-content-trust
(default true)
Push an image to a registry.
Usage: nerdctl push [OPTIONS] NAME[:TAG]
π€ ipfs://
prefix can be used for NAME
to push it to IPFS. See /docs/ipfs.md
for details.
Flags:
- π€
--platform=(amd64|arm64|...)
: Push content for a specific platform - π€
--all-platforms
: Push content for all platforms - π€
--sign
: Sign the image (none|cosign). Seedocs/cosign.md
for details. - π€
--cosign-key
: Path to the private key file, KMS, URI or Kubernetes Secret for--sign=cosign
- π€
--allow-nondistributable-artifacts
: Allow pushing images with non-distributable blobs - π€
--ipfs-address
: Multiaddr of IPFS API (default uses$IPFS_PATH
env variable if defined or local directory~/.ipfs
)
Unimplemented docker push
flags: --all-tags
, --disable-content-trust
(default true), --quiet
Load an image from a tar archive or STDIN.
π€ Supports both Docker Image Spec v1.2 and OCI Image Spec v1.0.
Usage: nerdctl load [OPTIONS]
Flags:
- π³
-i, --input
: Read from tar archive file, instead of STDIN - π€
--platform=(amd64|arm64|...)
: Import content for a specific platform - π€
--all-platforms
: Import content for all platforms
Unimplemented docker load
flags: --quiet
Save one or more images to a tar archive (streamed to STDOUT by default)
π€ The archive implements both Docker Image Spec v1.2 and OCI Image Spec v1.0.
Usage: nerdctl save [OPTIONS] IMAGE [IMAGE...]
Flags:
- π³
-o, --output
: Write to a file, instead of STDOUT - π€
--platform=(amd64|arm64|...)
: Export content for a specific platform - π€
--all-platforms
: Export content for all platforms
Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE.
Usage: nerdctl tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
Remove one or more images
Usage: nerdctl rmi [OPTIONS] IMAGE [IMAGE...]
Flags:
- π€
--async
: Asynchronous mode - π³
-f, --force
: Force removal of the image
Unimplemented docker rmi
flags: --no-prune
Display detailed information on one or more images.
Usage: nerdctl image inspect [OPTIONS] NAME|ID [NAME|ID...]
Flags:
- π€
--mode=(dockercompat|native)
: Inspection mode. "native" produces more information. - π³
--format
: Format the output using the given Go template, e.g,{{json .}}
- π€
--platform=(amd64|arm64|...)
: Inspect a specific platform
Show the history of an image.
Usage: nerdctl history [OPTIONS] IMAGE
Flags:
- π³
--no-trunc
: Don't truncate output - π³
-q, --quiet
: Only display snapshots IDs - π³
--format
: Format the output using the given Go template, e.g,{{json .}}
Remove unused images.
nerdctl image prune
requires --all to be specified.
Usage: nerdctl image prune [OPTIONS]
Flags:
- π³
-a, --all
: Remove all unused images, not just dangling ones - π³
-f, --force
: Do not prompt for confirmation
Unimplemented docker image prune
flags: --filter
Convert an image format.
e.g., nerdctl image convert --estargz --oci example.com/foo:orig example.com/foo:esgz
Usage: nerdctl image convert [OPTIONS] SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
Flags:
--estargz
: convert legacy tar(.gz) layers to eStargz for lazy pulling. Should be used in conjunction with '--oci'--estargz-record-in=<FILE>
: readctr-remote optimize --record-out=<FILE>
record file.β οΈ This flag is experimental and subject to change.--estargz-compression-level=<LEVEL>
: eStargz compression level (default: 9)--estargz-chunk-size=<SIZE>
: eStargz chunk size--estargz-min-chunk-size=<SIZE>
: The minimal number of bytes of data must be written in one gzip stream (requires stargz-snapshotter >= v0.13.0). Useful for creating a smaller eStargz image (refer to./docs/stargz.md
for details).--estargz-external-toc
: Separate TOC JSON into another image (called "TOC image"). The name of TOC image is the original + "-esgztoc" suffix. Both eStargz and the TOC image should be pushed to the same registry. (requires stargz-snapshotter >= v0.13.0) Useful for creating a smaller eStargz image (refer to./docs/stargz.md
for details).β οΈ This flag is experimental and subject to change.--estargz-keep-diff-id
: Convert to esgz without changing diffID (cannot be used in conjunction with '--estargz-record-in'. must be specified with '--estargz-external-toc')--zstdchunked
: Use zstd compression instead of gzip (a.k.a zstd:chunked). Should be used in conjunction with '--oci'--zstdchunked-record-in=<FILE>
: readctr-remote optimize --record-out=<FILE>
record file.β οΈ This flag is experimental and subject to change.--zstdchunked-compression-level=<LEVEL>
: zstd:chunked compression level (default: 3)--zstdchunked-chunk-size=<SIZE>
: zstd:chunked chunk size--uncompress
: convert tar.gz layers to uncompressed tar layers--oci
: convert Docker media types to OCI media types--platform=<PLATFORM>
: convert content for a specific platform--all-platforms
: convert content for all platforms (default: false)
Encrypt image layers. See ./docs/ocicrypt.md
.
Usage: nerdctl image encrypt [OPTIONS] SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
Example:
openssl genrsa -out mykey.pem
openssl rsa -in mykey.pem -pubout -out mypubkey.pem
nerdctl image encrypt --recipient=jwe:mypubkey.pem --platform=linux/amd64,linux/arm64 foo example.com/foo:encrypted
nerdctl push example.com/foo:encrypted
Env
and Cmd
.
To see non-encrypted information, run nerdctl image inspect --mode=native --platform=PLATFORM example.com/foo:encrypted
.
Flags:
--recipient=<RECIPIENT>
: Recipient of the image is the person who can decrypt (e.g.,jwe:mypubkey.pem
)--dec-recipient=<RECIPIENT>
: Recipient of the image; used only for PKCS7 and must be an x509 certificate--key=<KEY>[:<PWDDESC>]
: A secret key's filename and an optional password separated by colon, PWDDESC=|pass:|fd=|filename--gpg-homedir=<DIR>
: The GPG homedir to use; by default gpg uses ~/.gnupg--gpg-version=<VERSION>
: The GPG version ("v1" or "v2"), default will make an educated guess--platform=<PLATFORM>
: Convert content for a specific platform--all-platforms
: Convert content for all platforms (default: false)
Decrypt image layers. See ./docs/ocicrypt.md
.
Usage: nerdctl image decrypt [OPTIONS] SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
Example:
nerdctl pull --unpack=false example.com/foo:encrypted
nerdctl image decrypt --key=mykey.pem example.com/foo:encrypted foo:decrypted
Flags:
--dec-recipient=<RECIPIENT>
: Recipient of the image; used only for PKCS7 and must be an x509 certificate--key=<KEY>[:<PWDDESC>]
: A secret key's filename and an optional password separated by colon, PWDDESC=|pass:|fd=|filename--gpg-homedir=<DIR>
: The GPG homedir to use; by default gpg uses ~/.gnupg--gpg-version=<VERSION>
: The GPG version ("v1" or "v2"), default will make an educated guess--platform=<PLATFORM>
: Convert content for a specific platform--all-platforms
: Convert content for all platforms (default: false)
Log in to a container registry.
Usage: nerdctl login [OPTIONS] [SERVER]
Flags:
- π³
-u, --username
: Username - π³
-p, --password
: Password - π³
--password-stdin
: Take the password from stdin
Log out from a container registry
Usage: nerdctl logout [SERVER]
Create a network
βΉοΈ To isolate CNI bridge, CNI plugins v1.1.0 or later needs to be installed.
Usage: nerdctl network create [OPTIONS] NETWORK
Flags:
- π³
-d, --driver=(bridge|nat|macvlan|ipvlan)
: Driver to manage the Network- π³
--driver=bridge
: Default driver for unix - π³
--driver=macvlan
: Macvlan network driver for unix - π³
--driver=ipvlan
: IPvlan network driver for unix - π³ π¦
--driver=nat
: Default driver for windows
- π³
- π³
-o, --opt
: Set driver specific options- π³
--opt=com.docker.network.driver.mtu=<MTU>
: Set the containers network MTU - π€
--opt=mtu=<MTU>
: Alias of--opt=com.docker.network.driver.mtu=<MTU>
- π³
--opt=macvlan_mode=(bridge)>
: Set macvlan network mode (default: bridge) - π³
--opt=ipvlan_mode=(l2|l3)
: Set IPvlan network mode (default: l2) - π€
--opt=mode=(bridge|l2|l3)
: Alias of--opt=macvlan_mode=(bridge)
and--opt=ipvlan_mode=(l2|l3)
- π³
--opt=parent=<INTERFACE>
: Set valid parent interface on host
- π³
- π³
--ipam-driver=(default|host-local|dhcp)
: IP Address Management Driver- π³ π¦
--ipam-driver=default
: Default IPAM driver - π€
--ipam-driver=host-local
: Host-local IPAM driver for unix - π€
--ipam-driver=dhcp
: DHCP IPAM driver for unix, requires root
- π³ π¦
- π³
--ipam-opt
: Set IPAM driver specific options - π³
--subnet
: Subnet in CIDR format that represents a network segment, e.g. "10.5.0.0/16" - π³
--gateway
: Gateway for the master subnet - π³
--ip-range
: Allocate container ip from a sub-range - π³
--label
: Set metadata on a network
Unimplemented docker network create
flags: --attachable
, --aux-address
, --config-from
, --config-only
, --ingress
, --internal
, --ipv6
, --scope
List networks
Usage: nerdctl network ls [OPTIONS]
Flags:
- π³
-q, --quiet
: Only display network IDs - π³
--format
: Format the output using the given Go template- π³
--format=table
(default): Table - π³
--format='{{json .}}'
: JSON - π€
--format=wide
: Alias of--format=table
- π€
--format=json
: Alias of--format='{{json .}}'
- π³
Unimplemented docker network ls
flags: --filter
, --no-trunc
Display detailed information on one or more networks
Usage: nerdctl network inspect [OPTIONS] NETWORK [NETWORK...]
Flags:
- π³
--format
: Format the output using the given Go template, e.g,{{json .}}
- π€
--mode=(dockercompat|native)
: Inspection mode. "native" produces more information.
Unimplemented docker network inspect
flags: --verbose
Remove one or more networks by name or identifier
:warning network removal will fail if there are containers attached to it.
Usage: nerdctl network rm NETWORK [NETWORK...]
Remove all unused networks
Usage: nerdctl network prune [OPTIONS]
Flags:
- π³
-f, --force
: Do not prompt for confirmation
Unimplemented docker network prune
flags: --filter
Create a volume
Usage: nerdctl volume create [OPTIONS] [VOLUME]
Flags:
- π³
--label
: Set metadata for a volume
Unimplemented docker volume create
flags: --driver
, --opt
List volumes
Usage: nerdctl volume ls [OPTIONS]
Flags:
- π³
-q, --quiet
: Only display volume names - π³
--format
: Format the output using the given Go template- π³
--format=table
(default): Table - π³
--format='{{json .}}'
: JSON - π€
--format=wide
: Alias of--format=table
- π€
--format=json
: Alias of--format='{{json .}}'
- π³
- π€
--size
: Display the disk usage of volumes. - π³
-f, --filter
: Filter volumes based on given conditions.- π³
--filter label=<key>=<value>
: Matches volumes by label on bothkey
andvalue
. Ifvalue
is left empty, matches all volumes withkey
regardless of its value - π³
--filter name=<value>
: Matches all volumes with a name containing thevalue
string - π€
--filter "size=<value>"
: Matches all volumes with a size meets thevalue
.size
operand can be>=, <=, >, <, =
andvalue
must be an integer. Quotes should be used otherwise some shells may treat operand as redirections
- π³
Following arguments for --filter
are not supported yet:
--filter=dangling=true
: Filter volumes by dangling--filter=driver=local
: Filter volumes by driver
Display detailed information on one or more volumes
Usage: nerdctl volume inspect [OPTIONS] VOLUME [VOLUME...]
Flags:
- π³
--format
: Format the output using the given Go template, e.g,{{json .}}
- π€
--size
: Displays disk usage of volume
Remove one or more volumes
Usage: nerdctl volume rm [OPTIONS] VOLUME [VOLUME...]
- π³
-f, --force
: Force the removal of one or more volumes
Remove all unused local volumes
Usage: nerdctl volume prune [OPTIONS]
Flags:
- π³
-f, --force
: Do not prompt for confirmation
Unimplemented docker volume prune
flags: --filter
Create a new namespace.
Usage: nerdctl namespace create NAMESPACE
Flags:
--label
: Set labels for a namespace
Inspect a namespace.
Usage: nerdctl namespace inspect NAMESPACE
List containerd namespaces such as "default", "moby", or "k8s.io".
Usage: nerdctl namespace ls [OPTIONS]
Flags:
-q, --quiet
: Only display namespace names
Remove one or more namespaces.
Usage: nerdctl namespace remove [OPTIONS] NAMESPACE [NAMESPACE...]
Flags:
-c, --cgroup
: delete the namespace's cgroup
Udapte labels for a namespace.
Usage: nerdctl namespace update NAMESPACE
Flags:
--label
: Set labels for a namespace
Display the default AppArmor profile "nerdctl-default". Other profiles cannot be displayed with this command.
Usage: nerdctl apparmor inspect
Load the default AppArmor profile "nerdctl-default". Requires root.
Usage: nerdctl apparmor load
List the loaded AppArmor profile
Usage: nerdctl apparmor ls [OPTIONS]
Flags:
-q, --quiet
: Only display volume names--format
: Format the output using the given Go template, e.g,{{json .}}
Unload an AppArmor profile. The target profile name defaults to "nerdctl-default". Requires root.
Usage: nerdctl apparmor unload [PROFILE]
Clean up BuildKit build cache.
Usage: nerdctl builder prune
Flags:
- π€
--buildkit-host=<BUILDKIT_HOST>
: BuildKit address
Interactive debugging of Dockerfile using buildg.
Please refer to ./docs/builder-debug.md
for details.
This is an experimental feature.
buildkitd
daemon but uses the patched version of BuildKit provided by buildg. This should be fixed in the future.
Usage: nerdctl builder debug PATH
Flags:
- π€
-f
,--file
: Name of the Dockerfile - π€
--image
: Image to use for debugging stage - π€
--target
: Set the target build stage to build - π€
--build-arg
: Set build-time variables
Unimplemented docker builder prune
flags: --all
, --filter
, --force
, --keep-storage
Get real time events from the server.
Usage: nerdctl events [OPTIONS]
Flags:
- π³
--format
: Format the output using the given Go template, e.g,{{json .}}
Unimplemented docker events
flags: --filter
, --since
, --until
Display system-wide information
Usage: nerdctl info [OPTIONS]
Flags:
- π³
-f, --format
: Format the output using the given Go template, e.g,{{json .}}
- π€
--mode=(dockercompat|native)
: Information mode. "native" produces more information.
Show the nerdctl version information
Usage: nerdctl version [OPTIONS]
Flags:
- π³
-f, --format
: Format the output using the given Go template, e.g,{{json .}}
Remove unused data
nerdctl system prune
requires --all to be specified.
Usage: nerdctl system prune [OPTIONS]
Flags:
- π³
-a, --all
: Remove all unused images, not just dangling ones - π³
-f, --force
: Do not prompt for confirmation - π³
--volumes
: Prune volumes
Unimplemented docker system prune
flags: --filter
Display a live stream of container(s) resource usage statistics.
Usage: nerdctl stats [OPTIONS]
Flags:
- π³
-a, --all
: Show all containers (default shows just running) - π³
--format=FORMAT
: Pretty-print images using a Go template, e.g.,{{json .}}
- π³
--no-stream
: Disable streaming stats and only pull the first result - π³
--no-trunc
: Do not truncate output
Display the running processes of a container.
Usage: nerdctl top CONTAINER [ps OPTIONS]
Generate the autocompletion script for bash.
Usage: add the following line to ~/.bash_profile
:
source <(nerdctl completion bash)
Or run nerdctl completion bash > /etc/bash_completion.d/nerdctl
as the root.
Generate the autocompletion script for zsh.
Usage: see nerdctl completion zsh --help
Generate the autocompletion script for fish.
Usage: see nerdctl completion fish --help
Generate the autocompletion script for powershell.
Usage: see nerdctl completion powershell --help
Compose
Usage: nerdctl compose [OPTIONS] [COMMAND]
Flags:
- π³
-f, --file
: Specify an alternate compose file - π³
-p, --project-name
: Specify an alternate project name
Create and start containers
Usage: nerdctl compose up [OPTIONS] [SERVICE...]
Flags:
- π³
-d, --detach
: Detached mode: Run containers in the background - π³
--no-build
: Don't build an image, even if it's missing. - π³
--no-color
: Produce monochrome output - π³
--no-log-prefix
: Don't print prefix in logs - π³
--build
: Build images before starting containers. - π€
--ipfs
: Build images with pulling base images from IPFS. See./docs/ipfs.md
for details. - π³
--quiet-pull
: Pull without printing progress information - π³
--scale
: Scale SERVICE to NUM instances. Overrides thescale
setting in the Compose file if present. - π³
--remove-orphans
: Remove containers for services not defined in the Compose file
Unimplemented docker-compose up
(V1) flags: --no-deps
, --force-recreate
, --always-recreate-deps
, --no-recreate
,
--no-start
, --abort-on-container-exit
, --attach-dependencies
, --timeout
, --renew-anon-volumes
, --exit-code-from
Unimplemented docker compose up
(V2) flags: --environment
Create and start containers
Usage: nerdctl compose logs [OPTIONS] [SERVICE...]
Flags:
- π³
--no-color
: Produce monochrome output - π³
--no-log-prefix
: Don't print prefix in logs - π³
--timestamps
: Show timestamps - π³
--tail
: Number of lines to show from the end of the logs
Unimplemented docker compose logs
(V2) flags: --since
, --until
Build or rebuild services.
Usage: nerdctl compose build [OPTIONS] [SERVICE...]
Flags:
- π³
--build-arg
: Set build-time variables for services - π³
--no-cache
: Do not use cache when building the image - π³
--progress
: Set type of progress output (auto, plain, tty). Use plain to show container output - π€
--ipfs
: Build images with pulling base images from IPFS. See./docs/ipfs.md
for details.
Unimplemented docker-compose build
(V1) flags: --compress
, --force-rm
, --memory
, --no-rm
, --parallel
, --pull
, --quiet
Remove containers and associated resources
Usage: nerdctl compose down [OPTIONS]
Flags:
- π³
-v, --volumes
: Remove named volumes declared in the volumes section of the Compose file and anonymous volumes attached to containers
Unimplemented docker-compose down
(V1) flags: --rmi
, --remove-orphans
, --timeout
List images used by created containers in services
Usage: nerdctl compose images [OPTIONS] [SERVICE...]
Flags:
- π³
-q, --quiet
: Only show numeric image IDs
Stop containers in services without removing them.
Usage: nerdctl compose stop [OPTIONS] [SERVICE...]
Flags:
- π³
-t, --timeout
: Seconds to wait for stop before killing it (default 10)
List containers of services
Usage: nerdctl compose ps [OPTIONS] [SERVICE...]
Unimplemented docker-compose ps
(V1) flags: --quiet
, --services
, --filter
, --all
Unimplemented docker compose ps
(V2) flags: --status
Pull service images
Usage: nerdctl compose pull [OPTIONS] [SERVICE...]
Flags:
- π³
-q, --quiet
: Pull without printing progress information
Unimplemented docker-compose pull
(V1) flags: --ignore-pull-failures
, --parallel
, --no-parallel
, include-deps
Push service images
Usage: nerdctl compose push [OPTIONS] [SERVICE...]
Unimplemented docker-compose pull
(V1) flags: --ignore-push-failures
Validate and view the Compose file
Usage: nerdctl compose config
Flags:
- π³
-q, --quiet
: Pull without printing progress information - π³
--services
: Print the service names, one per line. - π³
--volumes
: Print the volume names, one per line. - π³
--hash="*"
: Print the service config hash, one per line.
Unimplemented docker-compose config
(V1) flags: --resolve-image-digests
, --no-interpolate
Unimplemented docker compose config
(V2) flags: --resolve-image-digests
, --no-interpolate
, --format
, --output
, --profiles
Force stop service containers
Usage: nerdctl compose kill [OPTIONS] [SERVICE...]
Flags:
- π³
-s, --signal
: SIGNAL to send to the container (default: "SIGKILL")
Restart containers of given (or all) services
Usage: nerdctl compose restart [OPTIONS] [SERVICE...]
Flags:
- π³
-t, --timeout
: Seconds to wait before restarting it (default 10)
Remove stopped service containers
Usage: nerdctl compose rm [OPTIONS] [SERVICE...]
Flags:
- π³
-f, --force
: Don't prompt for confirmation (different with-f
innerdctl rm
which means force deletion). - π³
-s, --stop
: Stop containers before removing. - π³
-v, --volumes
: Remove anonymous volumes associated with the container.
Run a one-off command on a service
Usage: nerdctl compose run [OPTIONS] SERVICE [COMMAND] [ARGS...]
Unimplemented docker-compose run
(V1) flags: --use-aliases
, --no-TTY
Unimplemented docker compose run
(V2) flags: --use-aliases
, --no-TTY
, --tty
Show the Compose version information (which is the nerdctl version)
Usage: nerdctl compose version
Flags:
- π³
-f, --format
: Format the output. Values: [pretty | json] (default "pretty") - π³
--short
: Shows only Compose's version number
P2P image distribution (IPFS) is completely optional. Your host is NOT connected to any P2P network, unless you opt in to install and run IPFS daemon.
Start read-only local registry backed by IPFS.
See ./docs/ipfs.md
for details.
Usage: nerdctl ipfs registry up [OPTIONS]
Flags:
- π€
--listen-registry
: Address to listen (defaultlocalhost:5050
) - π€
--read-retry-num
: Times to retry query on IPFS (default 0 (no retry)) - π€
--read-timeout
: Timeout duration of a read request to IPFS (default 0 (no timeout))
Stop and remove read-only local registry backed by IPFS.
See ./docs/ipfs.md
for details.
Usage: nerdctl ipfs registry down
Serve read-only registry backed by IPFS on localhost.
Use nerdctl ipfs registry up
.
Usage: nerdctl ipfs registry serve [OPTIONS]
Flags:
- π€
--ipfs-address
: Multiaddr of IPFS API (default is pulled from$IPFS_PATH/api
file. If$IPFS_PATH
env var is not present, it defaults to~/.ipfs
). - π€
--listen-registry
: Address to listen (defaultlocalhost:5050
). - π€
--read-retry-num
: Times to retry query on IPFS (default 0 (no retry)) - π€
--read-timeout
: Timeout duration of a read request to IPFS (default 0 (no timeout))
- π€ π¦
--address
: containerd address, optionally with "unix://" prefix - π€ π¦
-a
,--host
,-H
: deprecated aliases of--address
- π€ π¦
--namespace
: containerd namespace - π€ π¦
-n
: deprecated alias of--namespace
- π€ π¦
--snapshotter
: containerd snapshotter - π€ π¦
--storage-driver
: deprecated alias of--snapshotter
- π€ π¦
--cni-path
: CNI binary path (default:/opt/cni/bin
) [$CNI_PATH
] - π€ π¦
--cni-netconfpath
: CNI netconf path (default:/etc/cni/net.d
) [$NETCONFPATH
] - π€ π¦
--data-root
: nerdctl data root, e.g. "/var/lib/nerdctl" - π€
--cgroup-manager=(cgroupfs|systemd|none)
: cgroup manager- Default: "systemd" on cgroup v2 (rootful & rootless), "cgroupfs" on v1 rootful, "none" on v1 rootless
- π€
--insecure-registry
: skips verifying HTTPS certs, and allows falling back to plain HTTP
The global flags can be also specified in /etc/nerdctl/nerdctl.toml
(rootful) and ~/.config/nerdctl/nerdctl.toml
(rootless).
See ./docs/config.md
.
Container management:
docker attach
docker diff
docker checkpoint *
Image:
docker export
anddocker import
docker trust *
(Instead, nerdctl supportsnerdctl pull --verify=cosign
andnerdctl push --sign=cosign
. See./docs/cosign.md
.)docker manifest *
Network management:
docker network connect
docker network disconnect
Registry:
docker search
Compose:
docker-compose create|events|exec|pause|port|scale|start|top|unpause
Others:
docker system df
docker context
- Swarm commands are unimplemented and will not be implemented:
docker swarm|node|service|config|secret|stack *
- Plugin commands are unimplemented and will not be implemented:
docker plugin *
Configuration guide:
./docs/config.md
: Configuration (/etc/nerdctl/nerdctl.toml
,~/.config/nerdctl/nerdctl.toml
)./docs/registry.md
: Registry authentication (~/.docker/config.json
)
Basic features:
./docs/compose.md
: Compose./docs/rootless.md
: Rootless mode./docs/cni.md
: CNI for containers network./docs/build.md
:nerdctl build
with BuildKit
Advanced features:
./docs/stargz.md
: Lazy-pulling using Stargz Snapshotter./docs/nydus.md
: Lazy-pulling using Nydus Snapshotter./docs/overlaybd.md
: Lazy-pulling using OverlayBD Snapshotter./docs/ocicrypt.md
: Running encrypted images./docs/gpu.md
: Using GPUs inside containers./docs/multi-platform.md
: Multi-platform mode
Experimental features:
./docs/experimental.md
: Experimental features./docs/freebsd.md
: Running FreeBSD jails./docs/ipfs.md
: Distributing images on IPFS./docs/builder-debug.md
: Interactive debugging of Dockerfile
Implementation details:
./docs/dir.md
: Directory layout (/var/lib/nerdctl
)
Misc:
./docs/faq.md
: FAQs and Troubleshooting