# Command reference :whale: = Docker compatible :nerd_face: = nerdctl specific > [!NOTE] > - Unlisted `docker` CLI flags are unimplemented yet in `nerdctl` CLI. > It does not necessarily mean that the corresponding features are missing in containerd. > - Some commands and flags are only available on Linux. - [Container management](#container-management) - [:whale: nerdctl run](#whale-nerdctl-run) - [:whale: nerdctl exec](#whale-nerdctl-exec) - [:whale: nerdctl create](#whale-nerdctl-create) - [:whale: nerdctl cp](#whale-nerdctl-cp) - [:whale: nerdctl ps](#whale-nerdctl-ps) - [:whale: nerdctl inspect](#whale-nerdctl-inspect) - [:whale: nerdctl logs](#whale-nerdctl-logs) - [:whale: nerdctl port](#whale-nerdctl-port) - [:whale: nerdctl rm](#whale-nerdctl-rm) - [:whale: nerdctl stop](#whale-nerdctl-stop) - [:whale: nerdctl start](#whale-nerdctl-start) - [:whale: nerdctl restart](#whale-nerdctl-restart) - [:whale: nerdctl update](#whale-nerdctl-update) - [:whale: nerdctl wait](#whale-nerdctl-wait) - [:whale: nerdctl kill](#whale-nerdctl-kill) - [:whale: nerdctl pause](#whale-nerdctl-pause) - [:whale: nerdctl unpause](#whale-nerdctl-unpause) - [:whale: nerdctl rename](#whale-nerdctl-rename) - [:whale: nerdctl attach](#whale-nerdctl-attach) - [:whale: nerdctl container prune](#whale-nerdctl-container-prune) - [:whale: nerdctl diff](#whale-nerdctl-diff) - [:whale: nerdctl export](#whale-nerdctl-export) - [Build](#build) - [:whale: nerdctl build](#whale-nerdctl-build) - [:whale: nerdctl commit](#whale-nerdctl-commit) - [Image management](#image-management) - [:whale: nerdctl images](#whale-nerdctl-images) - [:whale: nerdctl pull](#whale-nerdctl-pull) - [:whale: nerdctl push](#whale-nerdctl-push) - [:whale: nerdctl load](#whale-nerdctl-load) - [:whale: nerdctl save](#whale-nerdctl-save) - [:whale: nerdctl import](#whale-nerdctl-import) - [:whale: nerdctl tag](#whale-nerdctl-tag) - [:whale: nerdctl rmi](#whale-nerdctl-rmi) - [:whale: nerdctl image inspect](#whale-nerdctl-image-inspect) - [:whale: nerdctl image history](#whale-nerdctl-image-history) - [:whale: nerdctl image prune](#whale-nerdctl-image-prune) - [:nerd_face: nerdctl image convert](#nerd_face-nerdctl-image-convert) - [:nerd_face: nerdctl image encrypt](#nerd_face-nerdctl-image-encrypt) - [:nerd_face: nerdctl image decrypt](#nerd_face-nerdctl-image-decrypt) - [Checkpoint management](#checkpoint-management) - [:whale: nerdctl checkpoint create](#whale-nerdctl-checkpoint-create) - [:whale: nerdctl checkpoint list](#whale-nerdctl-checkpoint-list) - [:whale: nerdctl checkpoint remove](#whale-nerdctl-checkpoint-remove) - [Manifest management](#manifest-management) - [:whale: nerdctl manifest annotate](#whale-nerdctl-manifest-annotate) - [:whale: nerdctl manifest create](#whale-nerdctl-manifest-create) - [:whale: nerdctl manifest inspect](#whale-nerdctl-manifest-inspect) - [:whale: nerdctl manifest push](#whale-nerdctl-manifest-push) - [:whale: nerdctl manifest rm](#whale-nerdctl-manifest-rm) - [Registry](#registry) - [:whale: nerdctl login](#whale-nerdctl-login) - [:whale: nerdctl logout](#whale-nerdctl-logout) - [:whale: nerdctl search](#whale-nerdctl-search) - [Network management](#network-management) - [:whale: nerdctl network create](#whale-nerdctl-network-create) - [:whale: nerdctl network ls](#whale-nerdctl-network-ls) - [:whale: nerdctl network inspect](#whale-nerdctl-network-inspect) - [:whale: nerdctl network rm](#whale-nerdctl-network-rm) - [:whale: nerdctl network prune](#whale-nerdctl-network-prune) - [Volume management](#volume-management) - [:whale: nerdctl volume create](#whale-nerdctl-volume-create) - [:whale: nerdctl volume ls](#whale-nerdctl-volume-ls) - [:whale: nerdctl volume inspect](#whale-nerdctl-volume-inspect) - [:whale: nerdctl volume rm](#whale-nerdctl-volume-rm) - [:whale: nerdctl volume prune](#whale-nerdctl-volume-prune) - [Namespace management](#namespace-management) - [:nerd_face: nerdctl namespace create](#nerd_face-nerdctl-namespace-create) - [:nerd_face: nerdctl namespace inspect](#nerd_face-nerdctl-namespace-inspect) - [:nerd_face: nerdctl namespace ls](#nerd_face-nerdctl-namespace-ls) - [:nerd_face: nerdctl namespace remove](#nerd_face-nerdctl-namespace-remove) - [:nerd_face: nerdctl namespace update](#nerd_face-nerdctl-namespace-update) - [AppArmor profile management](#apparmor-profile-management) - [:nerd_face: nerdctl apparmor inspect](#nerd_face-nerdctl-apparmor-inspect) - [:nerd_face: nerdctl apparmor load](#nerd_face-nerdctl-apparmor-load) - [:nerd_face: nerdctl apparmor ls](#nerd_face-nerdctl-apparmor-ls) - [:nerd_face: nerdctl apparmor unload](#nerd_face-nerdctl-apparmor-unload) - [Builder management](#builder-management) - [:whale: nerdctl builder prune](#whale-nerdctl-builder-prune) - [:nerd_face: nerdctl builder debug](#nerd_face-nerdctl-builder-debug) - [System](#system) - [:whale: nerdctl events](#whale-nerdctl-events) - [:whale: nerdctl info](#whale-nerdctl-info) - [:whale: nerdctl version](#whale-nerdctl-version) - [:whale: nerdctl system prune](#whale-nerdctl-system-prune) - [Stats](#stats) - [:whale: nerdctl stats](#whale-nerdctl-stats) - [:whale: nerdctl top](#whale-nerdctl-top) - [Shell completion](#shell-completion) - [:nerd_face: nerdctl completion bash](#nerd_face-nerdctl-completion-bash) - [:nerd_face: nerdctl completion zsh](#nerd_face-nerdctl-completion-zsh) - [:nerd_face: nerdctl completion fish](#nerd_face-nerdctl-completion-fish) - [:nerd_face: nerdctl completion powershell](#nerd_face-nerdctl-completion-powershell) - [Compose](#compose) - [:whale: nerdctl compose](#whale-nerdctl-compose) - [:whale: nerdctl compose up](#whale-nerdctl-compose-up) - [:whale: nerdctl compose logs](#whale-nerdctl-compose-logs) - [:whale: nerdctl compose build](#whale-nerdctl-compose-build) - [:whale: nerdctl compose create](#whale-nerdctl-compose-create) - [:whale: nerdctl compose exec](#whale-nerdctl-compose-exec) - [:whale: nerdctl compose down](#whale-nerdctl-compose-down) - [:whale: nerdctl compose images](#whale-nerdctl-compose-images) - [:whale: nerdctl compose start](#whale-nerdctl-compose-start) - [:whale: nerdctl compose stop](#whale-nerdctl-compose-stop) - [:whale: nerdctl compose port](#whale-nerdctl-compose-port) - [:whale: nerdctl compose ps](#whale-nerdctl-compose-ps) - [:whale: nerdctl compose pull](#whale-nerdctl-compose-pull) - [:whale: nerdctl compose push](#whale-nerdctl-compose-push) - [:whale: nerdctl compose pause](#whale-nerdctl-compose-pause) - [:whale: nerdctl compose unpause](#whale-nerdctl-compose-unpause) - [:whale: nerdctl compose config](#whale-nerdctl-compose-config) - [:whale: nerdctl compose cp](#whale-nerdctl-compose-cp) - [:whale: nerdctl compose kill](#whale-nerdctl-compose-kill) - [:whale: nerdctl compose restart](#whale-nerdctl-compose-restart) - [:whale: nerdctl compose rm](#whale-nerdctl-compose-rm) - [:whale: nerdctl compose run](#whale-nerdctl-compose-run) - [:whale: nerdctl compose top](#whale-nerdctl-compose-top) - [:whale: nerdctl compose version](#whale-nerdctl-compose-version) - [IPFS management](#ipfs-management) - [:nerd_face: nerdctl ipfs registry serve](#nerd_face-nerdctl-ipfs-registry-serve) - [Global flags](#global-flags) - [Unimplemented Docker commands](#unimplemented-docker-commands) ## Container management ### :whale: nerdctl run Run a command in a new container. Usage: `nerdctl run [OPTIONS] IMAGE [COMMAND] [ARG...]` :nerd_face: `ipfs://` prefix can be used for `IMAGE` to pull it from IPFS. See [`ipfs.md`](./ipfs.md) for details. :nerd_face: `oci-archive://` prefix can be used for `IMAGE` to specify a local file system path to an OCI formatted tarball. Basic flags: - :whale: `-a, --attach`: Attach STDIN, STDOUT, or STDERR - :whale: `-i, --interactive`: Keep STDIN open even if not attached" - :whale: `-t, --tty`: Allocate a pseudo-TTY - :warning: WIP: currently `-t` conflicts with `-d` - :whale: `-sig-proxy`: Proxy received signals to the process (default true) - :whale: `-d, --detach`: Run container in background and print container ID - :whale: `--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. - :whale: `--rm`: Automatically remove the container when it exits - :whale: `--pull=(always|missing|never)`: Pull image before running - Default: "missing" - :whale: `-q, --quiet`: Suppress the pull output - :whale: `--pid=(host|container:)`: PID namespace to use - :whale: `--uts=(host)` : UTS namespace to use - :whale: `--stop-signal`: Signal to stop a container (default "SIGTERM") - :whale: `--stop-timeout`: Timeout (in seconds) to stop a container - :whale: `--detach-keys`: Override the default detach keys Platform flags: - :whale: `--platform=(amd64|arm64|...)`: Set platform Init process flags: - :whale: `--init`: Run an init inside the container that forwards signals and reaps processes. - :nerd_face: `--init-binary=`: The custom init binary to use. We suggest you use the [tini](https://github.com/krallin/tini) binary which is used in Docker project to get the same behavior. Please make sure the binary exists in your `PATH`. - Default: `tini` Isolation flags: - :whale: :nerd_face: `--isolation=(default|process|host|hyperv)`: Used on Windows to change process isolation level. `default` will use the runtime options configured in `default_runtime` in the [containerd configuration](https://github.com/containerd/containerd/blob/master/docs/cri/config.md#cri-plugin-config-guide) which is `process` in containerd by default. `process` runs process isolated containers. `host` runs [Host Process containers](https://kubernetes.io/docs/tasks/configure-pod-container/create-hostprocess-pod/). Host process containers inherit permissions from containerd process unless `--user` is specified then will start with user specified and the user specified must be present on the host. `host` requires Containerd 1.7+. `hyperv` runs Hyper-V hypervisor partition-based isolated containers. Not implemented for Linux. Network flags: - :whale: `--net, --network=(bridge|host|none|container:|ns:|)`: Connect a container to a network. - Default: "bridge" - `container:`: reuse another container's network stack, container has to be precreated. - :nerd_face: `ns:`: run inside an existing network namespace - :nerd_face: Unlike Docker, this flag can be specified multiple times (`--net foo --net bar`) - :whale: `-p, --publish`: Publish a container's port(s) to the host - :whale: `--dns`: Set custom DNS servers - :whale: `--dns-search`: Set custom DNS search domains - :whale: `--dns-opt, --dns-option`: Set DNS options - :whale: `-h, --hostname`: Container host name - :whale: `--domainname`: Container domain name - :whale: `--add-host`: Add a custom host-to-IP mapping (host:ip). `ip` could be a special string `host-gateway`, - which will be resolved to the `host-gateway-ip` in nerdctl.toml or global flag. - :whale: `--ip`: Specific static IP address(es) to use. Note that unlike docker, nerdctl allows specifying it with the default bridge network. - :whale: `--ip6`: Specific static IP6 address(es) to use. Should be used with user networks - :whale: `--mac-address`: Specific MAC address to use. Be aware that it does not check if manually specified MAC addresses are unique. Supports network type `bridge` and `macvlan` Resource flags: - :whale: `--cpus`: Number of CPUs - :whale: `--cpu-quota`: Limit the CPU CFS (Completely Fair Scheduler) quota - :whale: `--cpu-period`: Limit the CPU CFS (Completely Fair Scheduler) period - :whale: `--cpu-shares`: CPU shares (relative weight) - :whale: `--cpuset-cpus`: CPUs in which to allow execution (0-3, 0,1) - :whale: `--cpuset-mems`: Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems - :whale: `--cpu-rt-period`: Limit CPU real-time period in microseconds. Only supported with cgroup v1. - :whale: `--cpu-rt-runtime`: Limit CPU real-time runtime in microseconds. Only supported with cgroup v1. - :whale: `--memory`: Memory limit - :whale: `--memory-reservation`: Memory soft limit - :whale: `--memory-swap`: Swap limit equal to memory plus swap: '-1' to enable unlimited swap - :whale: `--memory-swappiness`: Tune container memory swappiness (0 to 100) (default -1) - :whale: `--kernel-memory`: Kernel memory limit (deprecated) - :whale: `--oom-kill-disable`: Disable OOM Killer - :whale: `--oom-score-adj`: Tune container’s OOM preferences (-1000 to 1000, rootless: 100 to 1000) - :whale: `--pids-limit`: Tune container pids limit - :nerd_face: `--cgroup-conf`: Configure cgroup v2 (key=value) - :whale: `--blkio-weight`: Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) - :whale: `--blkio-weight-device`: Block IO weight (relative device weight) - :whale: `--device-read-bps`: Limit read rate (bytes per second) from a device - :whale: `--device-read-iops`: Limit read rate (IO per second) from a device - :whale: `--device-write-bps`: Limit write rate (bytes per second) to a device - :whale: `--device-write-iops`: Limit write rate (IO per second) to a device - :whale: `--cgroupns=(host|private)`: Cgroup namespace to use - Default: "private" on cgroup v2 hosts, "host" on cgroup v1 hosts - :whale: `--cgroup-parent`: Optional parent cgroup for the container - :whale: `--device`: Add a host device to the container Intel RDT flags: - :nerd_face: `--rdt-class=CLASS`: Name of the RDT class (or CLOS) to associate the container wit User flags: - :whale: `-u, --user`: Username or UID (format: [:]) - :nerd_face: `--umask`: Set the umask inside the container. Defaults to 0022. Corresponds to Podman CLI. - :whale: `--group-add`: Add additional groups to join - :whale: `--userns`: Set it to `host` to disable user namespacing set in nerdctl.toml or in cli. Security flags: - :whale: `--security-opt seccomp=`: specify custom seccomp profile - :whale: `--security-opt apparmor=`: specify custom AppArmor profile - :whale: `--security-opt no-new-privileges`: disallow privilege escalation, e.g., setuid and file capabilities - :whale: `--security-opt systempaths=unconfined`: Turn off confinement for system paths (masked paths, read-only paths) for the container - :whale: `--security-opt writable-cgroups`: making the cgroups writeable - :nerd_face: `--security-opt privileged-without-host-devices`: Don't pass host devices to privileged containers - :whale: `--cap-add=`: Add Linux capabilities - :whale: `--cap-drop=`: Drop Linux capabilities - :whale: `--privileged`: Give extended privileges to this container - :nerd_face: `--systemd=(true|false|always)`: Enable systemd compatibility (default: false). - Default: "false" - true: Enable systemd compatibility is enabled if the entrypoint executable matches one of the following paths: - `/sbin/init` - `/usr/sbin/init` - `/usr/local/sbin/init` - always: Always enable systemd compatibility Corresponds to Podman CLI. Runtime flags: - :whale: `--runtime`: Runtime to use for this container, e.g. \"crun\", or \"io.containerd.runsc.v1\". - :whale: `--sysctl`: Sysctl options, e.g \"net.ipv4.ip_forward=1\" Volume flags: - :whale: `-v, --volume :[:]`: Bind mount a volume, e.g., `-v /mnt:/mnt:rro,rprivate` - :whale: option `rw` : Read/Write (when writable) - :whale: option `ro` : Non-recursive read-only - :nerd_face: option `rro`: Recursive read-only. Should be used in conjunction with `rprivate`. 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](https://github.com/opencontainers/runc/pull/3272)). With older runc, `rro` just works as `ro`. - :whale: option `shared`, `slave`, `private`: Non-recursive "shared" / "slave" / "private" propagation - :whale: option `rshared`, `rslave`, `rprivate`: Recursive "shared" / "slave" / "private" propagation - :nerd_face: option `bind`: Not-recursively bind-mounted - :nerd_face: option `rbind`: Recursively bind-mounted - unimplemented options: `:z` and `:Z` (SELinux relabeling) - :whale: `--tmpfs`: Mount a tmpfs directory, e.g. `--tmpfs /tmp:size=64m,exec`. - :whale: `--mount`: Attach a filesystem mount to the container. Consists of multiple key-value pairs, separated by commas and each consisting of a `=` tuple. e.g., `-- mount type=bind,source=/src,target=/app,bind-propagation=shared`. - :whale: `type`: Current supported mount types are `bind`, `volume`, `tmpfs`. The default type will be set to `volume` if not specified. i.e., `--mount src=vol-1,dst=/app,readonly` equals `--mount type=volume,src=vol-1,dst=/app,readonly` - unimplemented type: `image` - Common Options: - :whale: `src`, `source`: Mount source spec for bind and volume. Mandatory for bind. - :whale: `dst`, `destination`, `target`: Mount destination spec. - :whale: `readonly`, `ro`, `rw`, `rro`: Filesystem permissions. - Options specific to `bind`: - :whale: `bind-propagation`: `shared`, `slave`, `private`, `rshared`, `rslave`, or `rprivate`(default). - :whale: `bind-nonrecursive`: `true` or `false`(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`: - :whale: `tmpfs-size`: Size of the tmpfs mount in bytes. Unlimited by default. - :whale: `tmpfs-mode`: File mode of the tmpfs in **octal**. Defaults to `1777` or world-writable. - Options specific to `volume`: - unimplemented options: `volume-nocopy`, `volume-label`, `volume-driver`, `volume-opt` - :whale: `--volumes-from`: Mount volumes from the specified container(s), e.g. "--volumes-from my-container". Rootfs flags: - :whale: `--read-only`: Mount the container's root filesystem as read only - :nerd_face: `--rootfs`: The first argument is not an image but the rootfs to the exploded container. Corresponds to Podman CLI. Env flags: - :whale: `--entrypoint`: Overwrite the default ENTRYPOINT of the image - :whale: `-w, --workdir`: Working directory inside the container - :whale: `-e, --env`: Set environment variables - :whale: `--env-file`: Set environment variables from file Metadata flags: - :whale: `--name`: Assign a name to the container - :whale: `-l, --label`: Set meta data on a container (Not passed through the OCI runtime since nerdctl v2.0, with an exception for `nerdctl/bypass4netns`) - :whale: `--label-file`: Read in a line delimited file of labels - :whale: `--annotation`: Add an annotation to the container (passed through to the OCI runtime) - :whale: `--cidfile`: Write the container ID to the file - :nerd_face: `--pidfile`: file path to write the task's pid. The CLI syntax conforms to Podman convention. Health check flags: - :whale: `--health-cmd`: Command to run to check container health - :whale: `--health-interval`: Time between running the check (e.g., 30s, 1m) - :whale: `--health-timeout`: Time to wait before considering the check failed (e.g., 5s) - :whale: `--health-retries`: Number of failures before container is considered unhealthy - :whale: `--health-start-period`: Start period for the container to initialize before starting health-retries countdown - :whale: `--health-start-interval`: Interval between checks during the start period - :whale: `--no-healthcheck`: Disable any health checks defined by image or CLI Logging flags: - :whale: `--log-driver=(json-file|journald|fluentd|syslog|none)`: Logging driver for the container (default `json-file`). - :whale: `--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: - :whale: `--log-opt=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. - :whale: `--log-opt=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 when `max-size` is also set. A positive integer. Defaults to 1. - :nerd_face: `--log-opt=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 `.1`. - Default: `////-json.log` - Example: `/var/lib/nerdctl/1935db59/containers/default//-json.log` - :whale: `--log-opt labels=production_status,geo`: A comma-separated list of logging-related labels this daemon accepts. - :whale: `--log-opt env=os,customer`: A comma-separated list of logging-related environment variables this daemon accepts. - :whale: `--log-driver=journald`: Writes log messages to `journald`. The `journald` daemon must be running on the host machine. - :whale: `--log-opt=tag=