nerdctl Documentation

File: README.md Copy Chapter

[⬇️ Download]
[📖 Command reference]
[❓FAQs & Troubleshooting]
[📚 Additional documents]

nerdctl: Docker-compatible CLI for containerd

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.

Examples Copy Chapter

Basic usage Copy Section

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.

Debugging Kubernetes Copy Section

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 read logs (experimental):

# nerdctl --namespace=k8s.io ps -a
CONTAINER ID    IMAGE                                                      COMMAND                   CREATED          STATUS    PORTS    NAMES
...
e8793b8cca8b    registry.k8s.io/coredns/coredns:v1.9.3                     "/coredns -conf /etc…"    2 minutes ago    Up                 k8s://kube-system/coredns-787d4945fb-mfx6b/coredns
...

# nerdctl --namespace=k8s.io logs -f e8793b8cca8b
[INFO] plugin/reload: Running configuration SHA512 = 591cf328cccc12bc490481273e738df59329c62c0b729d94e8b61db9961c2fa5f046dd37f1cf888b953814040d180f52594972691cd6ff41be96639138a43908
CoreDNS-1.9.3
linux/amd64, go1.18.2, 45b0a11
...

Rootless mode Copy Section

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.

Install Copy Chapter

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.
• BuildKit (OPTIONAL): for using nerdctl build. BuildKit daemon (buildkitd) needs to be running. See also the document about setting up BuildKit.
  • v0.11.0 or later is highly recommended. Some features, such as pruning caches with nerdctl system prune, do not work with older versions.
• RootlessKit (OPTIONAL): for Rootless mode
  • RootlessKit needs to be v0.10.0 or later. v3.0.0 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.

Brew Copy Section

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.

macOS Copy Section

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

Windows Copy Section

Install with Scoop:

scoop install nerdctl

Regarding compatibility, note that:

• Linux containers: Known to work on WSL2
• Windows containers: experimental support for Windows (see below for features that are currently known to work)

FreeBSD Copy Section

See ./docs/freebsd.md.

Docker Copy Section

To run containerd and nerdctl inside Docker:

docker build -t nerdctl .
docker run -it --rm --privileged nerdctl

Motivation Copy Chapter

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.

Features present in `nerdctl` but not present in Docker Copy Chapter

Major:

• On-demand image pulling (lazy-pulling) using Stargz/Nydus/OverlayBD/SOCI Snapshotter: nerdctl --snapshotter=stargz|nydus|overlaybd|soci 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.
• Cosign integration: nerdctl pull --verify=cosign and nerdctl push --sign=cosign, and in Compose
• Accelerated rootless containers using bypass4netns: nerdctl run --annotation nerdctl/bypass4netns=true

Minor:

• Namespacing: nerdctl --namespace=<NS> ps .
  (NOTE: All Kubernetes containers are in the k8s.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=.
  Use sudo nerdctl apparmor load to load the nerdctl-default profile.
• Systemd compatibility support: nerdctl run --systemd=always

Trivial:

• Inspecting raw OCI config: nerdctl container inspect --mode=native .

Features implemented in `nerdctl` ahead of Docker Copy Chapter

• 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.
  The same feature was later introduced in Docker v25 with a different syntax: read-only mounts are now recursively read-only by default when supported,
  and the behavior is customizable with --mount type=bind,...,readonly,bind-recursive=<enabled|disabled|writable|readonly>.
  nerdctl now supports the Docker v25 syntax too, and the old rro syntax is deprecated.

Similar tools Copy Chapter

• ctr: incompatible with Docker CLI, and not friendly to users.
  Notably, ctr lacks the equivalents of the following nerdctl commands:

  • nerdctl run -p
  • nerdctl run --restart=always --net=bridge
  • nerdctl pull with ~/.docker/config.json and credential helper binaries such as docker-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 and kim push

• PouchContainer (abandoned?): needs an extra daemon

Developer guide Copy Chapter

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:

• Project governance,
• Maintainers,
• and Contributing guidelines

information in our containerd/project repository.

Compiling nerdctl from source Copy Section

Run make && sudo make install.

See the header of go.mod for the minimum supported version of Go.

Using go install github.com/containerd/nerdctl/v2/cmd/nerdctl is possible, but unrecommended because it does not fill version strings printed in nerdctl version

Testing Copy Section

See testing nerdctl.

Contributing to nerdctl Copy Section

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.

Command reference

Moved to ./docs/command-reference.md

Additional documents

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/soci.md: Lazy-pulling using SOCI 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

File: docs/dev/auditing_dockerfile.md Copy Chapter

Auditing dockerfile

Because of the nature of GitHub cache, and the time it takes to build the dockerfile for testing, it is desirable
to be able to audit what is going on there.

This document provides a few pointers on how to do that, and some results as of 2025-02-26 (run inside lima, nerdctl main,
on a macbook pro M1).

Intercept network traffic Copy Chapter

On macOS Copy Section

Use Charles:

• start SSL proxying
• enable SOCKS proxy
• export the root certificate

On linux Copy Section

Left as an exercise to the reader.

If using lima Copy Section

• restart your lima instance with HTTP_PROXY=http://X.Y.Z.W:8888 HTTPS_PROXY=socks5://X.Y.Z.W:8888 limactl start instance - where XYZW
  is the local ip of the Charles proxy (non-localhost)

On the host where you are running containerd Copy Section

• copy the root certificate from above into /usr/local/share/ca-certificates/charles-ssl-proxying-certificate.crt
• update your host: sudo update-ca-certificates
• now copy the root certificate again to your current nerdctl clone

Hack the dockerfile to insert our certificate Copy Section

Add the following stages in the dockerfile:

FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-trixie AS hack-build-base-debian
RUN apt-get update -qq; apt-get -qq install ca-certificates
COPY charles-ssl-proxying-certificate.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS hack-build-base
RUN apk add --no-cache ca-certificates
COPY charles-ssl-proxying-certificate.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

FROM ubuntu:${UBUNTU_VERSION} AS hack-base
RUN apt-get update -qq; apt-get -qq install ca-certificates
COPY charles-ssl-proxying-certificate.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

Then replace any later "FROM" with our modified bases:

golang:${GO_VERSION}-trixie => hack-build-base-debian
golang:${GO_VERSION}-alpine => hack-build-base
ubuntu:${UBUNTU_VERSION} => hack-base

Mimicking what the CI is doing Copy Chapter

A quick helper:

run(){
  local no_cache="${1:-}"
  local platform="${2:-arm64}"
  local dockerfile="${3:-Dockerfile}"
  local target="${4:-test-integration}"

  local cache_shard="$CONTAINERD_VERSION"-"$platform"
  local shard="$cache_shard"-"$target"-"$UBUNTU_VERSION"-"$no_cache"-"$dockerfile"

  local cache_location=$HOME/bk-cache-"$cache_shard"
  local destination=$HOME/bk-output-"$shard"
  local logs="$HOME"/bk-debug-"$shard"

  if [ "$no_cache" != "" ]; then
    nerdctl system prune -af
    nerdctl builder prune -af
    rm -Rf "$cache_location"
  fi

  nerdctl build \
    --build-arg UBUNTU_VERSION="$UBUNTU_VERSION" \
    --build-arg CONTAINERD_VERSION="$CONTAINERD_VERSION" \
    --platform="$platform" \
    --output type=tar,dest="$destination" \
    --progress plain \
    --build-arg HTTP_PROXY=$HTTP_PROXY \
    --build-arg HTTPS_PROXY=$HTTPS_PROXY \
    --cache-to type=local,dest="$cache_location",mode=max \
    --cache-from type=local,src="$cache_location" \
    --target "$target" \
    -f "$dockerfile" . 2>&1 | tee "$logs"
}

And here is what the CI is doing:

ci_run(){
  local no_cache="${1:-}"
  export UBUNTU_VERSION=24.04

  # The actual version may differ
  CONTAINERD_VERSION=v1.7.25 run "$no_cache"  arm64 Dockerfile.origin build-dependencies
  UBUNTU_VERSION=22.04 CONTAINERD_VERSION=v1.7.25 run "" arm64 Dockerfile.origin test-integration

  CONTAINERD_VERSION=v2.0.3 run "$no_cache"  arm64 Dockerfile.origin build-dependencies
  UBUNTU_VERSION=24.04 CONTAINERD_VERSION=v2.0.3 run "" arm64 Dockerfile.origin test-integration

  CONTAINERD_VERSION=v2.0.3 run "$no_cache"  amd64 Dockerfile.origin build-dependencies
  UBUNTU_VERSION=24.04 CONTAINERD_VERSION=v2.0.3 run "" amd64 Dockerfile.origin test-integration
}

# To simulate what happens when there is no cache, go with:
ci_run no_cache

# Once you have a cached run, you can simulate what happens with cache
# First modify something in the nerdctl tree
# Then run it
touch mimick_nerdctl_change
ci_run

Analyzing results Copy Chapter

Network Copy Section

Full CI run, cold cache (the first three pipelines, and part of the fourth)

The following numbers are based on the above script, with cold cache.

Unfortunately golang did segfault on me during the last (cross-run targetting amd), so, these numbers should be taken
as (slightly) underestimated.

Total number of requests: 7190

Total network duration: 13 minutes 11 seconds

Outbound: 1.31MB

Inbound: 5202MB

Breakdown per domain

Full CI run, warm cache (only the first three pipelines)

Analysis

Docker Hub

Images from Docker Hub are clearly a source of concern (made even worse by the fact they apply strict limitations on the
number of requests permitted).

When the cache is cold, this is about 1GB per run, for 200 requests and 3 minutes.

Actions:

• reduce the number of images
  • we currently use 2 golang images, which does not make sense
• reduce the round trips
  • there is no reason why any of the images should be queried more than once per build
• move away from Hub golang image, and instead use a raw distro + golang download
  • Hub golang is a source of pain and issues (diverging version scheme forces ugly shell contorsions, delay in availability creates
    broken situations)
  • we are already downloading the go release tarball anyhow, so, this is just wasted bandwidth with no added value

Success criteria:

• on a cold cache, reduce the total number of requests against Docker properties by 50% or more
• on a cold cache, cut the data transfer and time in half

Distro packages

On a WARM cache, close to 1 minute is spent fetching Ubuntu packages.
This should not happen, and distro downloads should always be cached.

On a cold cache, distro packages download near 3 minutes.
Very likely there is stage duplication that could be reduced and some of that could be cut of.

Actions:

• ensure distro package downloading is staged in a way we can cache it
• review stages to reduce package installation duplication

Success criteria:

• 0 package installation on a warm cache
• cut cold cache package install time by 50% (XXX not realistic?)

GitHub repositories

Clones from GitHub do clock in at 1GB on a cold cache.
Containerd alone counts for more than half of it (at 160MB+ x4).

Hopefully, on a warm cache it is practically non-existent.

But then, this is ridiculous.

Actions:

• shallow clone

Success criteria:

• reduce network traffic from cloning by 80%

Go modules

At 750+MB and over 4 minutes, this is the number one speed bottleneck on a cold cache.

On a warm cache, it is still over 150MB and 30+ seconds.

In and of itself, this is hard to reduce, as we need these...

Actions:

• we could cache the module download location to reduce round-trips on modules that are shared across
  different projects
• we are likely installing nerdctl modules six times - (once per architecture during the build phase, then once per
  ubuntu version and architecture during the tests runs (this is not even accounted for in the audit above)) - it should
  only happen twice (once per architecture)

Success criteria:

• achieve 20% reduction of total time spent downloading go modules

Other downloads

1. At 500MB+ and 30 seconds, storage.googleapis.com is serving a SINGLE go module that gets special treatment: klauspost/compress.
   This module is very small, but does serve along with it a very large testdata folder.
   The fact that nerdctl downloads its module multiple times is further compounding the effect.

2. the golang archive is downloaded multiple times - it should be downloaded only once per run, and only on a cold cache

3. some of the binary releases we are retrieving are also being retrieved with a warm cache, and they are generally quite large.
   We could consider building certain things from source instead, and in all cases ensure that we are only downloading with a cold cache.

Success criteria:

• 0 static downloads on a warm cache
• cut extra downloads by 20%

Duration

Unscientific numbers, per pipeline

dependencies, no cache:

• 224 seconds total
• 53 seconds exporting cache

dependencies, with cache:

• 12 seconds

test-integration, no cache:

• 282 seconds

Caching

Number of layers in cache:

after dependencies stage: 78
intermediate size: 1.5G
after test-integration stage: 118
total size: 2.8G

Generic considerations Copy Chapter

Caching compression Copy Section

This is obviously heavily dependent on the runner properties.

With local cache, on high-performance IO (laptop SSD), zstd is definitely considerably better (about twice as fast).

With GHA, the impact is minimal, since network IO is heavily dominant, but zstd still has the upper
hand with regard to cache size.

Output Copy Section

Loading image into the Docker store comes at a somewhat significant cost.
It is quite possible that a significant performance boost could be achieved by using
buildkit containerd worker and nerdctl instead.

File: docs/dev/store.md Copy Chapter

About `pkg/store`

TL;DR Copy Chapter

You may want to read this if you are developing something in nerdctl that would involve storing persistent information.

If there is a "store" already in the codebase (eg: volumestore, namestore, etc) that does provide the methods that you need,
you are fine and should just stick to that.

On the other hand, if you are curious, or if what you want to write is "new", then you should have a look at this document:
it does provide extended information about how we manage persistent data storage, especially with regard to concurrency
and atomicity.

Motivation Copy Chapter

The core of nerdctl aims at keeping its dependencies as lightweight as possible.
For that reason, nerdctl does not use a database to store persistent information, but instead uses the filesystem,
under a variety of directories.

That "information" is typically volumes metadata, containers lifecycle info, the "name store" (which does ensure no two
containers can be named the same), etc.

However, storing data on the filesystem in a reliable way comes with challenges:

• incomplete writes may happen (because of a system restart, or an application crash), leaving important structured files
  in a broken state
• concurrent writes, or reading while writing would obviously be a problem as well, be it across goroutines, or between
  concurrent executions of the nerdctl binary, or embedded in a third-party application that does concurrently access resources

The pkg/store package does provide a "storage" abstraction that takes care of these issues, generally providing
guarantees that concurrent operations can be performed safely, and that writes are "atomic", ensuring we never brick
user installs.

For details about how, and what is done, read-on.

The problem with writing a file Copy Chapter

A write may very well be interrupted.

While reading the resulting mangled file will typically break json.Unmarshall for example, and while we should still
handle such cases gracefully and provide meaningful information to the user about which file is damaged (which could be due
to the user manually modifying them), using "atomic" writes will (almost always (*)) prevent this from happening
on our part.

An "atomic" write is usually performed by first writing data to a temporary file, and then, only if the write operation
succeeded, move that temporary file to its final destination.

The rename syscall (see https://man7.org/linux/man-pages/man2/rename.2.html) is indeed "atomic"
(eg: it fully succeeds, or fails), providing said guarantees that you end-up with a complete file that has the entirety
of what was meant to be written.

This is an "almost always", as an operating system crash MAY break that promise (this is highly dependent on specifics
that are out of scope here, and that nerdctl has no control over).
Though, crashing operating systems is (hopefully) a sufficiently rare event that we can consider we "always" have atomic writes.

There is one caveat with "rename-based atomic writes" though: if you mount the file itself inside a container,
an atomic write will not work as you expect, as the inode will (obviously) change when you modify the file,
and these changes will not be propagated inside the container.

This caveat is the reason why hostsstore does NOT use an atomic write to update the hosts file, but a traditional write.

Concurrency between go routines Copy Chapter

This is a (simple) well-known problem. Just use a mutex to prevent concurrent modifications of the same object.

Note that this is not much of a problem right now in nerdctl itself - but it might be in third-party applications using
our codebase.

This is just generally good hygiene when building concurrency-safe packages.

Concurrency between distinct binary invocations Copy Chapter

This is much more of a problem.

There are many good reasons and real-life scenarios where concurrent binary execution may happen.
A third-party deployment tool (similar to terraform for eg), that will batch a bunch of operations to be performed
to achieve a desired infrastructure state, and call many nerdctl invocations in parallel to achieve that.
This is also common-place in testing (subpackages).
And of course, a third-party tool that would be long-running and allow parallel execution, leveraging nerdctl codebase
as a library, may certainly produce these circumstances.

The known answer to that problem is to use a filesystem lock (or flock).

Concretely, the first process will "lock" a directory. All other processes trying to do the same will then be put
in a queue and wait for the prior lock to be released before they can "lock" themselves, in turn.

Filesystem locking comes with its own set of challenges:

• implementation is somewhat low-level (the golang core library keeps their implementation internal, and you have to
  reimplement your own with platform-dependent APIs and syscalls)
• it is tricky to get right - there are reasons why golang core does not make it public
• locking "scope" should be done carefully: having ONE global lock for everything will definitely hurt performance badly,
  as you will basically make everything "sequential", effectively destroying some of the benefits of parallelizing code
  in the first place...

Lock design... Copy Chapter

While it is tempting to just provide self-locking, individual methods as an API (Get, Set), this is not the right
answer.

Imagine a context where consuming code would first like to check if something exists, then later on create it if it does not:

if !store.Exists("something") {
	// do things
	// ...
	// Now, create
	store.Set([]byte("data"), "something")
}

You do have two methods (Get and Set) that may individually guarantee they are the sole user of that resource,
but a concurrent change in between these two calls may very well (and will) happen and change the state of the world.

Effectively, in that case, Set might overwrite changes made by another go routine or concurrent execution, possibly
wrecking havoc in another process.

When to lock, and for how long, is a decision that only the embedding code can make.

A good example is container creation.
It may require the creation of several different volumes.
In that case, you want to lock at the start of the container creation process, and only release the lock when you are fully
done creating the container - not just when done creating a volume (nor even when done creating all volumes).

... while safeguarding the developer Copy Chapter

nerdctl still provides some safeguards for the developer.

Any store method that DOES require locking will fail loudly if it does not detect a lock.

This is obviously not bullet-proof.
For example, the lock may belong to another goroutine instead of the one we are in (and we cannot detect that).
But this is still better than nothing, and will help developers making sure they do lock.

Using the `store` api to implement your own storage Copy Chapter

While - as mentioned above - the store does not lock on its own, specific "stores implementations" may, and should,
provide higher-level methods that best fit their data-model usage, and that do lock on their own.

For example, the namestore (which is the simplest store), does provide three simple methods:

• Acquire
• Release
• Rename

Users of the namestore do not have to bother with locking. These methods are safe to use concurrently.

This is a good example of how to leverage core store primitives to implement a developer friendly, safe storage for
"something" (in that case "names").

Finally note an important point - mentioned above: locking should be done to the smallest possible "segment" of sub-directories.
Specifically, any store should lock only - at most - resources under the namespace being manipulated.

For example, a container lifecycle storage should not lock out any other container, but only its own private directory.

Scope, ambitions and future Copy Chapter

pkg/store has no ambition whatsoever to be a generic solution, usable outside nerdctl.

It is solely designed to fit nerdctl needs, and if it was to be made usable standalone, would probably have to be modified
extensively, which is clearly out of scope here.

Furthermore, there are already much more advanced generic solutions out there that you should use instead for outside-of-nerdctl projects.

As for future, one nice thing we should consider is to implement read-only locks in addition to the exclusive, write-locks
we currently use.
The net benefit would be a performance boost in certain contexts (massively parallel, mostly read environments).

File: docs/testing/README.md Copy Chapter

Testing nerdctl

This document covers basic usage of nerdctl testing tasks, and generic recommendations
and principles about writing tests.

For more comprehensive information about nerdctl test tools, see tools.md.

Code, fix, lint, rinse, repeat Copy Chapter

# Do hack

# When done:
# This will ensure proper import formatting, modules, and basic formatting of your code
make fix

# And this will run all linters and report if any modification is required
make lint

Note that both these tasks will work on any OS, including macOS.

Also note that make lint does call on subtask make lint-commits which is going to lint commits for the range
main..HEAD by default (this is fine for most development flows that expect to be merged in main).

If you are targeting a specific branch that is not main (for example working against release/1.7),
you likely want to explicitly set the commit range to that instead.

eg:
LINT_COMMIT_RANGE=target_branch..HEAD make lint-commits
or
LINT_COMMIT_RANGE=target_branch..HEAD make lint

Unit testing Copy Chapter

# This will run basic unit testing
make test

This task must be run on a supported OS (linux, windows, or freebsd).

Integration testing Copy Chapter

TL;DR Copy Section

Be sure to first make && sudo make install

# Test all with nerdctl (rootless mode, if running go as a non-root user)
go test -p 1 ./cmd/nerdctl/...

# Test all with nerdctl rootful
go test -p 1 -exec sudo ./cmd/nerdctl/...

# Test all with docker
go test -p 1 ./cmd/nerdctl/... -args -test.target=docker

# Test just the tests(s) which names match TestVolume.*
go test -p 1 ./cmd/nerdctl/... -run "TestVolume.*"
# Or alternatively, just test the subpackage
go test ./cmd/nerdctl/volume

About parallelization Copy Section

By default, when go test ./foo/... finds subpackages, it does create a separate test binary
per sub-package, and execute them in parallel.
This effectively will make distinct tests in different subpackages to be executed in
parallel, regardless of whether they called t.Parallel or not.

The -p 1 flag does inhibit this behavior, and forces go to run each sub-package
sequentially.

Note that this is different from the --parallel flag, which controls the amount of
parallelization that a single go test binary will use when faced with tests that do
explicitly allow it (with a call to t.Parallel()).

Or provision a test environment with Docker-built artifacts Copy Section

Docker can be used to build all the dependencies needed to run the integration tests
(containerd, runc, CNI plugins, BuildKit, snapshotters, etc.), which can then be installed
on the host (this is what the CI does). These scripts substantially and irreversibly modify
the host, so they refuse to run unless GITHUB_ACTIONS=true is set - only do this on a
disposable machine:

docker buildx build --target out-test-integration-artifacts --output type=local,dest=/tmp/nerdctl-test-artifacts .
sudo env GITHUB_ACTIONS=true ./hack/provisioning/linux/test-integration-env.sh install /tmp/nerdctl-test-artifacts rootful
./hack/test-integration.sh -test.target=nerdctl -test.only-flaky=false

For rootless (rootless, or rootless-port-slirp4netns):

sudo env GITHUB_ACTIONS=true ./hack/provisioning/linux/test-integration-env.sh install /tmp/nerdctl-test-artifacts rootless
GITHUB_ACTIONS=true ./hack/test-integration-rootless.sh ./hack/test-integration.sh -test.target=nerdctl -test.only-flaky=false

Principles Copy Section

Tests should be parallelized (with best effort)

General case

It should be possible to parallelize all tests - as such, please make sure you:

• name all resources your test is manipulating after the test identifier (data.Identifier())
  to guarantee your test will not interact with other tests
• do NOT use os.Setenv - instead, use Setenv on the command you are running
• use t.Parallel() at the beginning of your test (and subtests as well of course)
• in the very exceptional case where your test for some reason can NOT be parallelized, be sure to mark it explicitly as such
  with a comment explaining why

For "blanket" destructive operations

If you are going to use blanket destructive operations (like prune), please:

• use a dedicated namespace: add nerdtest.Private to the test Requirements
• since docker does not support namespaces, be sure to:
  • only enable Parallel if the target is NOT docker: if !nerdtest.IsDocker() { t.Parallel() }
  • double check that what you do in the default namespace is safe

Clean-up after (and before) yourself

• do NOT use defer, use t.Cleanup
• do NOT test the result of commands doing the cleanup - it is fine if they fail,
  and they are not test failure per-se - they are here to garbage collect
• you should call your cleanup routine BEFORE doing anything, in case there is any
  leftovers from previous runs, typically:

tearDown := func(){
    // Do some cleanup
}

tearDown()
t.Cleanup(tearDown)

Test what you are testing, and not something else

You should only test atomically.

If you are testing nerdctl volume create, make sure that your test will not fail
because of changes in nerdctl volume inspect.

That obviously means there are certain things you cannot test "yet".
Just put the right test in the right place with this simple rule of thumb:
if your test requires another nerdctl command to validate the result, then it does
not belong here. Instead, it should be a test for that other command.

Of course, this is not perfect, and changes in create may now fail in inspect tests
while create could be faulty, but it does beat the alternative, because of this principle:
it is easier to walk backwards from a failure.

File: docs/testing/tools.md Copy Chapter

Nerdctl testing tools

Preamble Copy Chapter

The integration test suite in nerdctl is meant to apply to both nerdctl and docker,
and further support additional test properties to target specific contexts (ipv6, kube).

Basic usage is covered in the testing docs.

This here covers how to write tests, leveraging nerdctl pkg/testutil/test
which has been specifically developed to take care of repetitive tasks,
protect the developer against unintended side effects across tests, and generally
encourage clear testing structure with good debug-ability and a relatively simple API for
most cases.

Using `test.Case` Copy Chapter

Starting from scratch, the simplest, basic structure of a new test is:

package main

import (
	"testing"

	"github.com/containerd/nerdctl/v2/pkg/testutil/nerdtest"
	"github.com/containerd/nerdctl/mod/tigron/test"
	"github.com/containerd/nerdctl/mod/tigron/require"
	"github.com/containerd/nerdctl/mod/tigron/expect"
)

func TestMyThing(t *testing.T) {
	// Declare your test
	myTest := nerdtest.Setup()
	// This is going to run `nerdctl info` (or `docker info`)
	myTest.Command = test.Command("info")
    // Verify the command exits with 0, and stdout contains the word `Kernel`
    myTest.Expected = test.Expects(0, nil, expect.Contains("Kernel"))
	// Run it
	myTest.Run(t)
}

Expectations Copy Chapter

There are a handful of helpers for "expectations".

You already saw two (test.Expects and test.Contains):

First, test.Expects(exitCode int, errors []error, outputCompare Comparator), which is
convenient to quickly describe what you expect overall.

exitCode is obvious (note that passing -1 as an exit code will just
verify the commands does fail without comparing the code, and -2 will not verify the exit
code at all).

errors is a slice of go error, that allows you to compare what is seen on stderr
with existing errors (for example: errdefs.ErrNotFound), or more generally
any string you want to match.

outputCompare can be either your own comparison function, or
one of the comparison helper.

Secondly, test.Contains - which is a Comparator.

Comparators Copy Section

Besides expect.Contains(string), there are a few more:

• expect.DoesNotContain(string)
• expect.Equals(string)
• expect.Match(*regexp.Regexp)
• expect.All(comparators ...Comparator), which allows you to bundle together a bunch of other comparators

The following example shows how to implement your own custom Comparator
(this is actually the Equals comparator).

package whatever

import (
	"testing"

	"gotest.tools/v3/assert"

	"github.com/containerd/nerdctl/mod/tigron/expect"
	"github.com/containerd/nerdctl/mod/tigron/require"
	"github.com/containerd/nerdctl/mod/tigron/test"
	"github.com/containerd/nerdctl/mod/tigron/tig"
)

func MyComparator(compare string) test.Comparator {
	return func(stdout string, t tig.T) {
		t.Helper()
		assert.Assert(t, stdout == compare)
	}
}

Advanced expectations Copy Section

You may want to have expectations that contain a certain piece of data
that is being used in the command or at other stages of your test (Setup).

For example, creating a container with a certain name, you might want to verify
that this name is then visible in the list of containers.

To achieve that, you should write your own Manager, leveraging test Data.

Here is an example, where we are using data.Labels().Get("sometestdata").

package main

import (
	"errors"
	"testing"

	"gotest.tools/v3/assert"

	"github.com/containerd/errdefs"

	"github.com/containerd/nerdctl/mod/tigron/expect"
	"github.com/containerd/nerdctl/mod/tigron/require"
	"github.com/containerd/nerdctl/mod/tigron/test"
	"github.com/containerd/nerdctl/mod/tigron/tig"

	"github.com/containerd/nerdctl/v2/pkg/testutil/nerdtest"
)

func TestMyThing(t *testing.T) {
	nerdtest.Setup()

	// Declare your test
	myTest := &test.Case{
		Data:        test.WithLabels(map[string]string{"sometestdata": "blah"}),
		Command:     test.Command("info"),
		Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
			return &test.Expected{
				ExitCode: 1,
				Errors: []error{
					errors.New("foobla"),
					errdefs.ErrNotFound,
				},
				Output: func(stdout string, t tig.T) {
					assert.Assert(t, stdout == data.Labels().Get("sometestdata"))
				},
			}
		},
	}

	myTest.Run(t)
}

On `Data` Copy Chapter

Data is provided to allow storing mutable key-value information that pertain to the test.

While it can be provided through test.WithLabels(map[string]string{key: value}),
inside the testcase definition, it can also be dynamically manipulated inside Setup, or Command.

Note that Data additionally exposes the following functions:

• Identifier(words ...string) which returns a unique identifier associated with the current test (or subtest)
• TempDir() which returns the private, temporary directory associated with the test

... along with the Get(key) and Set(key, value) methods.

Note that Data is copied down to subtests, which is convenient to pass "down"
information relevant to a bunch of subtests (eg: like a registry IP).

On Config Copy Chapter

Config is similar to Data, although it is meant specifically for predefined
keys that impact the base behavior of the binary you are testing.

You can initiate your config using test.WithConfig(key, value), and you can
manipulate it further using helpers.Read andhelpers.Write.

Currently, the following keys are defined:

• DockerConfig allowing to set custom content for the $DOCKER_CONFIG/config.json file
• Namespace (default to nerdctl-test if unspecified, but see "mode private")
• NerdctlToml to set custom content for the $NERDCTL_TOML file
• HostsDir to specify the value of the arg --hosts-dir
• DataRoot to specify the value of the arg --data-root
• Debug to enable debug (works for both nerdctl and docker)

Note that config defined on the test case is copied over for subtests.

Commands Copy Chapter

For simple cases, test.Command(args ...string) is the way to go.

It will execute the binary to test (nerdctl or docker), with the provided arguments,
and will by default get cwd inside the temporary directory associated with the test.

Environment Copy Section

You can attach custom environment variables for your test in the Env property of your
test.

These will be automatically added to the environment for your command, and also
your setup and cleanup routines (see below).

If you would like to override the environment specifically for a command, but not for
others (eg: in Setup or Cleanup), you can do so with custom commands (see below).

Note that environment as defined statically in the test will be copied over for subtests.

Working directory Copy Section

By default, the working directory of the command will be set to the temporary directory
of the test.

This behavior can be overridden using custom commands.

Custom Executor Copy Section

Custom Executors allow you to manipulate test Data, override important aspects
of the command to execute (Env, WorkingDir), or otherwise give you full control
on what the command does.

You just need to implement an Executor:

package main

import (
	"errors"
	"testing"

	"gotest.tools/v3/assert"

	"github.com/containerd/errdefs"

	"github.com/containerd/nerdctl/mod/tigron/expect"
	"github.com/containerd/nerdctl/mod/tigron/require"
	"github.com/containerd/nerdctl/mod/tigron/test"
	"github.com/containerd/nerdctl/mod/tigron/tig"

	"github.com/containerd/nerdctl/v2/pkg/testutil/nerdtest"
)

func TestMyThing(t *testing.T) {
	nerdtest.Setup()

	// Declare your test
	myTest := &test.Case{
		Data:        test.WithLabels(map[string]string{"sometestdata": "blah"}),
		Command: func(data test.Data, helpers test.Helpers) test.TestableCommand {
			return helpers.Command("run", "--name", data.Labels().Get("sometestdata"))
		},
		Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
			return &test.Expected{
				ExitCode: 1,
				Errors: []error{
					errors.New("foobla"),
					errdefs.ErrNotFound,
				},
				Output: func(stdout string, t tig.T) {
					assert.Assert(t, stdout == data.Labels().Get("sometestdata"))
				},
			}
		},
	}

	myTest.Run(t)
}

Note that inside your Executor you do have access to the full palette of command options,
including:

• Background(timeout time.Duration) which allows you to background a command execution
• WithWrapper(binary string, args ...string) which allows you to "wrap" your command with another binary
• WithStdin(io.Reader) which allows you to pass a reader to the command stdin
• WithCwd(string) which allows you to specify the working directory (default to the test temp directory)
• Clone() which returns a copy of the command, with env, cwd, etc

and also WithBinary and WithArgs.

On `helpers` Copy Section

Inside a custom Executor, Manager, or Butler, you have access to a collection of
helpers to simplify command execution:

• helpers.Ensure(args ...string) will run a command and ensure it exits successfully
• helpers.Fail(args ...string) will run a command and ensure it fails
• helpers.Anyhow(args ...string) will run a command but does not care if it succeeds or fails
• helpers.Capture(args ...string) will run a command, ensure it is successful, and return the output
• helpers.Command(args ...string) will return a command that can then be tested against expectations
• helpers.Custom(binary string, args ...string) will do the same for any arbitrary command (not limited to nerdctl)
• helpers.T() which returns the appropriate *testing.T for your context

Setup and Cleanup Copy Chapter

Tests routinely require a set of actions to be performed before you can run the
command you want to test.
A setup routine will get executed before your Command, and have access to and can
manipulate your test Data and Config.

Conversely, you very likely want to clean things up once your test is done.
While temporary directories are cleaned for you with no action needed on your part,
the app you are testing might have stateful data you may want to remove.
Note that a Cleanup routine will get executed twice - after your Command has run
its course evidently - but also, pre-emptively, before your Setup, so that possible leftovers from
previous runs are taken care of.

package main

import (
	"errors"
	"testing"

	"gotest.tools/v3/assert"

	"github.com/containerd/errdefs"

	"github.com/containerd/nerdctl/mod/tigron/expect"
	"github.com/containerd/nerdctl/mod/tigron/require"
	"github.com/containerd/nerdctl/mod/tigron/test"
	"github.com/containerd/nerdctl/mod/tigron/tig"

	"github.com/containerd/nerdctl/v2/pkg/testutil/nerdtest"
)

func TestMyThing(t *testing.T) {
	nerdtest.Setup()

	// Declare your test
	myTest := &test.Case{
		Data:        test.WithLabels(map[string]string{"sometestdata": "blah"}),
		Setup: func(data *test.Data, helpers test.Helpers){
			helpers.Ensure("volume", "create", "foo")
			helpers.Ensure("volume", "create", "bar")
		},
		Cleanup: func(data *test.Data, helpers test.Helpers){
			helpers.Anyhow("volume", "rm", "foo")
			helpers.Anyhow("volume", "rm", "bar")
		},
		Command: func(data test.Data, helpers test.Helpers) test.TestableCommand {
			return helpers.Command("run", "--name", data.Identifier()+data.Labels().Get("sometestdata"))
		},
		Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
			return &test.Expected{
				ExitCode: 1,
				Errors: []error{
					errors.New("foobla"),
					errdefs.ErrNotFound,
				},
				Output: func(stdout string, t tig.T) {
					assert.Assert(t, stdout == data.Labels().Get("sometestdata"))
				},
			}
		},
	}

	myTest.Run(t)
}

Subtests Copy Chapter

Subtests are just regular tests, attached to the SubTests slice of a test.

Note that a subtest will inherit its parent Data, Config and Env, in the state they are at
after the parent test has run its Setup and Command routines (but before Cleanup).
This does not apply to Identifier() and TempDir(), which are unique to the subtest.

Also note that a test does not have to have a Command.
This is a convenient pattern if you just need a common Setup for a bunch of subtests.

Parallelism Copy Chapter

All tests (and subtests) are assumed to be parallelizable.

You can force a specific test.Case to not be run in parallel though,
by setting its NoParallel property to true.

Note that if you want better isolation, it is usually better to use the requirement
nerdtest.Private instead of NoParallel (see below).

Requirements Copy Chapter

test.Case has a Require property that allow enforcing specific, per-test requirements.

A Requirement is expected to make you Skip tests when the environment does not match
expectations.

Here are a few:

/* Detailed source-code truncated for AI context efficiency. */

About `nerdtest.Private` Copy Section

While all requirements above are self-descriptive or obvious, nerdtest.Private is a
special case.

If set, it will run tests inside a dedicated namespace that is private to the test.
Note that subtests by default are going to be set in that same namespace, unless they
ask for private as well, or they reset the Namespace config key.

If the target is Docker - which does not support namespaces - asking for Private
will disable parallelization.

The purpose of private is to provide a truly clean-room environment for tests
that are going to have side effects on others, or that do require an exclusive, pristine
environment.

Using private is generally preferable to disabling parallelization, as doing the latter
would slow down the run and won't have the same isolation guarantees about the environment.

Advanced command customization Copy Chapter

Testing any non-trivial binary likely assume a good amount of custom code
to set up the right default behavior wrt environment, flags, etc.

To do that, you can pass a test.Testable implementation to the test.Customize method.

It basically lets you define your own CustomizableCommand, along with a hook to deal with
ambient requirements that is run after test.Require and before test.Setup.

CustomizableCommand are typically embedding a test.GenericCommand and overriding both the
Run and Clone methods.

Check the nerdtest implementation for details.

Utilities Copy Chapter

TBD

File: docs/build.md Copy Chapter

Setting up `nerdctl build` with BuildKit

nerdctl build (and nerdctl compose build) relies on BuildKit.
To use it, you need to set up BuildKit.

BuildKit has 2 types of backends.

• containerd worker: BuildKit relies on containerd to manage containers and images, etc. containerd needs to be up-and-running on the host.
• OCI worker: BuildKit manages containers and images, etc. containerd isn't needed. This worker relies on runc for container execution.

You need to set up BuildKit with either of the above workers.

Note that OCI worker cannot access base images (FROM images in Dockerfiles) managed by containerd.
Thus you cannot let nerdctl build use containerd-managed images as the base image.
They include images previously built using nerdctl build.

For example, the following build bar fails with OCI worker because it tries to use the previously built and containerd-managed image foo.

$ mkdir -p /tmp/ctx && cat <<EOF > /tmp/ctx/Dockerfile
FROM ghcr.io/stargz-containers/ubuntu:20.04-org
RUN echo hello
EOF
$ nerdctl build -t foo /tmp/ctx
$ cat <<EOF > /tmp/ctx/Dockerfile
FROM foo
RUN echo bar
EOF
$ nerdctl build -t bar /tmp/ctx

This limitation can be avoided using containerd worker as mentioned later.

Setting up BuildKit with containerd worker Copy Chapter

Rootless Copy Section

$ CONTAINERD_NAMESPACE=default containerd-rootless-setuptool.sh install-buildkit-containerd

containerd-rootless-setuptool.sh is aware of CONTAINERD_NAMESPACE and CONTAINERD_SNAPSHOTTER envvars.
It installs buildkitd to the specified containerd namespace.
This allows BuildKit using containerd-managed images in that namespace as the base image.
Note that BuildKit can't use images in other namespaces as of now.

If CONTAINERD_NAMESPACE envvar is not specified, this script configures buildkitd to use "buildkit" namespace (not "default" namespace).

You can install an additional buildkitd process in a different namespace by executing this script with specifying the namespace with CONTAINERD_NAMESPACE.

BuildKit will expose the socket at $XDG_RUNTIME_DIR/buildkit-$CONTAINERD_NAMESPACE/buildkitd.sock if CONTAINERD_NAMESPACE is specified.
If CONTAINERD_NAMESPACE is not specified, that location will be $XDG_RUNTIME_DIR/buildkit/buildkitd.sock.

Rootful Copy Section

$ sudo systemctl enable --now buildkit

Then add the following configuration to /etc/buildkit/buildkitd.toml to enable containerd worker.

[worker.oci]
  enabled = false

[worker.containerd]
  enabled = true
  # namespace should be "k8s.io" for Kubernetes (including Rancher Desktop)
  namespace = "default"

Setting up BuildKit with OCI worker Copy Chapter

Rootless Copy Section

$ containerd-rootless-setuptool.sh install-buildkit

As mentioned in the above, BuildKit with this configuration cannot use images managed by containerd.
They include images previously built with nerdctl build.

BuildKit will expose the socket at $XDG_RUNTIME_DIR/buildkit/buildkitd.sock.

rootful Copy Section

$ sudo systemctl enable --now buildkit

Which BuildKit socket will nerdctl use? Copy Chapter

You can specify BuildKit address for nerdctl build using --buildkit-host flag or BUILDKIT_HOST envvar.
When BuildKit address isn't specified, nerdctl tries some default BuildKit addresses the following order and uses the first available one.

• <runtime directory>/buildkit-<current namespace>/buildkitd.sock
• <runtime directory>/buildkit-default/buildkitd.sock
• <runtime directory>/buildkit/buildkitd.sock

For example, if you run rootless nerdctl with test containerd namespace, it tries to use $XDG_RUNTIME_DIR/buildkit-test/buildkitd.sock by default then try to fall back to $XDG_RUNTIME_DIR/buildkit-default/buildkitd.sock and $XDG_RUNTIME_DIR/buildkit/buildkitd.sock

File: docs/builder-debug.md Copy Chapter

Interactive debugging of Dockerfile (Experimental)

nerdctl supports interactive debugging of Dockerfile as nerdctl builder debug.

$ nerdctl builder debug /path/to/context

This feature leverages buildg, interactive debugger of Dockerfile.
For command reference, please refer to the Command reference doc in buildg repo.

:warning: This command currently doesn't use the host's buildkitd daemon but uses the patched version of BuildKit provided by buildg. This should be fixed to use the host's buildkitd in the future.

Example Copy Chapter

Example Dockerfile:

FROM busybox AS build1
RUN echo a > /a
RUN echo b > /b
RUN echo c > /c

Example debugging:

$ nerdctl builder debug --image=ubuntu:22.04 /tmp/ctx/
WARN[2022-05-17T10:15:48Z] using host network as the default#1 [internal] load .dockerignore
#1 transferring context: 2B done
#1 DONE 0.1s

#2 [internal] load build definition from Dockerfile
#2 transferring dockerfile: 108B done
#2 DONE 0.1s

#3 [internal] load metadata for docker.io/library/busybox:latest
INFO[2022-05-17T10:15:51Z] debug session started. type "help" for command reference.
Filename: "Dockerfile"
 =>   1| FROM busybox AS build1
      2| RUN echo a > /a
      3| RUN echo b > /b
      4| RUN echo c > /c
(buildg) break 3
(buildg) breakpoints
[0]: line: Dockerfile:3
[on-fail]: breaks on fail
(buildg) continue
#3 DONE 3.1s

#4 [1/4] FROM docker.io/library/busybox@sha256:d2b53584f580310186df7a2055ce3ff83cc0df6caacf1e3489bff8cf5d0af5d8
#4 resolve docker.io/library/busybox@sha256:d2b53584f580310186df7a2055ce3ff83cc0df6caacf1e3489bff8cf5d0af5d8 0.0s done
#4 sha256:50e8d59317eb665383b2ef4d9434aeaa394dcd6f54b96bb7810fdde583e9c2d1 0B / 772.81kB 0.2s
#4 sha256:50e8d59317eb665383b2ef4d9434aeaa394dcd6f54b96bb7810fdde583e9c2d1 0B / 772.81kB 5.3s
#4 sha256:50e8d59317eb665383b2ef4d9434aeaa394dcd6f54b96bb7810fdde583e9c2d1 0B / 772.81kB 10.4s
#4 sha256:50e8d59317eb665383b2ef4d9434aeaa394dcd6f54b96bb7810fdde583e9c2d1 772.81kB / 772.81kB 11.4s done
#4 extracting sha256:50e8d59317eb665383b2ef4d9434aeaa394dcd6f54b96bb7810fdde583e9c2d1 0.1s done
#4 DONE 20.2s

#5 [2/4] RUN echo a > /a
#5 DONE 0.1s
Breakpoint[0]: reached line: Dockerfile:3
Filename: "Dockerfile"
      1| FROM busybox AS build1
      2| RUN echo a > /a
*=>   3| RUN echo b > /b
      4| RUN echo c > /c
(buildg) exec --image sh
# ls /debugroot/
a  b  bin  dev	etc  home  proc  root  tmp  usr  var
# cat /debugroot/a /debugroot/b
a
b
#
(buildg) quit

File: docs/cni.md Copy Chapter

Using CNI with nerdctl

nerdctl uses CNI plugins for its container network, you can set network by
either --network or --net option.

Basic networks Copy Chapter

nerdctl support some basic types of CNI plugins without any configuration
needed(you should have CNI plugin be installed), for Linux systems the basic
CNI plugin types are bridge, portmap, firewall, tuning, for Windows
system, the supported CNI plugin types are nat only.

The default network bridge for Linux and nat for Windows if you
don't set any network options.

Configuration of the default network bridge of Linux:

{
  "cniVersion": "1.0.0",
  "name": "bridge",
  "plugins": [
    {
      "type": "bridge",
      "bridge": "nerdctl0",
      "isGateway": true,
      "ipMasq": true,
      "hairpinMode": true,
      "ipam": {
        "type": "host-local",
        "routes": [{ "dst": "0.0.0.0/0" }],
        "ranges": [
          [
            {
              "subnet": "10.4.0.0/24",
              "gateway": "10.4.0.1"
            }
          ]
        ]
      }
    },
    {
      "type": "portmap",
      "capabilities": {
        "portMappings": true
      }
    },
    {
      "type": "firewall",
      "ingressPolicy": "same-bridge"
    },
    {
      "type": "tuning"
    }
  ]
}

Bridge isolation Copy Chapter

nerdctl >= 0.18 sets the ingressPolicy to same-bridge when firewall plugin >= 1.1.0 is installed.
This ingressPolicy replaces the CNI isolation plugin used in nerdctl <= 0.17.

When firewall plugin >= 1.1.0 is not found, nerdctl does not enable the bridge isolation.
This means a container in --net=foo can connect to a container in --net=bar.

macvlan/IPvlan networks Copy Chapter

nerdctl also support macvlan and IPvlan network driver.

To create a macvlan network which bridges with a given physical network interface, use --driver macvlan with
nerdctl network create command.

# nerdctl network create mac0 --driver macvlan \
  --subnet=192.168.5.0/24
  --gateway=192.168.5.2
  -o parent=eth0

You can specify the parent, which is the interface the traffic will physically go through on the host,
defaults to default route interface.

And the subnet should be under the same network as the network interface,
an easier way is to use DHCP to assign the IP:

# nerdctl network create mac0 --driver macvlan --ipam-driver=dhcp

Using --driver ipvlan can create ipvlan network, the default mode for IPvlan is l2.

DHCP host-name and other DHCP options Copy Chapter

Nerdctl automatically sets the DHCP host-name option to the hostname value of the container.

Furthermore, on network creation, nerdctl supports the ability to set other DHCP options through --ipam-options.

Currently, the following options are supported by the DHCP plugin:

dhcp-client-identifier
subnet-mask
routers
user-class
vendor-class-identifier

For example:

# nerdctl network create --driver macvlan \
    --ipam-driver dhcp \
    --ipam-opt 'vendor-class-identifier={"type": "provide", "value": "Hey! Its me!"}' \
    my-dhcp-net

Custom networks Copy Chapter

You can also customize your CNI network by providing configuration files.

When rootful, the expected root location is /etc/cni/net.d.
For rootless, the expected root location is ~/.config/cni/net.d/

Configuration files (like 10-mynet.conf) can be placed either in the root location,
or under a subfolder.
If in the root location, this network will be available to all nerdctl namespaces.
If placed in a subfolder, it will be available only to the identically named namespace.

For example, you have one configuration file(/etc/cni/net.d/10-mynet.conf)
for bridge network:

{
  "cniVersion": "1.0.0",
  "name": "mynet",
  "type": "bridge",
  "bridge": "cni0",
  "isGateway": true,
  "ipMasq": true,
  "ipam": {
    "type": "host-local",
    "subnet": "172.19.0.0/24",
    "routes": [
      { "dst": "0.0.0.0/0" }
    ]
  }
}

This will configure a new CNI network with the name mynet, and you can use
this network to create a container in any namespace:

# nerdctl run -it --net mynet --rm alpine ip addr show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host
       valid_lft forever preferred_lft forever
3: eth0@if6120:  mtu 1500 qdisc noqueue state UP
    link/ether 5e:5b:3f:0c:36:56 brd ff:ff:ff:ff:ff:ff
    inet 172.19.0.51/24 brd 172.19.0.255 scope global eth0
       valid_lft forever preferred_lft forever
    inet6 fe80::5c5b:3fff:fe0c:3656/64 scope link tentative
       valid_lft forever preferred_lft forever

File: docs/command-reference.md Copy Chapter

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
  • :whale: nerdctl run
  • :whale: nerdctl exec
  • :whale: nerdctl create
  • :whale: nerdctl cp
  • :whale: nerdctl ps
  • :whale: nerdctl inspect
  • :whale: nerdctl logs
  • :whale: nerdctl port
  • :whale: nerdctl rm
  • :whale: nerdctl stop
  • :whale: nerdctl start
  • :whale: nerdctl restart
  • :whale: nerdctl update
  • :whale: nerdctl wait
  • :whale: nerdctl kill
  • :whale: nerdctl pause
  • :whale: nerdctl unpause
  • :whale: nerdctl rename
  • :whale: nerdctl attach
  • :whale: nerdctl container prune
  • :whale: nerdctl diff
  • :whale: nerdctl export
• Build
  • :whale: nerdctl build
  • :whale: nerdctl commit
• Image management
  • :whale: nerdctl images
  • :whale: nerdctl pull
  • :whale: nerdctl push
  • :whale: nerdctl load
  • :whale: nerdctl save
  • :whale: nerdctl import
  • :whale: nerdctl tag
  • :whale: nerdctl rmi
  • :whale: nerdctl image inspect
  • :whale: nerdctl image history
  • :whale: nerdctl image prune
  • :nerd_face: nerdctl image convert
  • :nerd_face: nerdctl image encrypt
  • :nerd_face: nerdctl image decrypt
• Checkpoint management
  • :whale: nerdctl checkpoint create
  • :whale: nerdctl checkpoint list
  • :whale: nerdctl checkpoint remove
• Manifest management
  • :whale: nerdctl manifest annotate
  • :whale: nerdctl manifest create
  • :whale: nerdctl manifest inspect
  • :whale: nerdctl manifest push
  • :whale: nerdctl manifest rm
• Registry
  • :whale: nerdctl login
  • :whale: nerdctl logout
  • :whale: nerdctl search
• Network management
  • :whale: nerdctl network create
  • :whale: nerdctl network ls
  • :whale: nerdctl network inspect
  • :whale: nerdctl network rm
  • :whale: nerdctl network prune
• Volume management
  • :whale: nerdctl volume create
  • :whale: nerdctl volume ls
  • :whale: nerdctl volume inspect
  • :whale: nerdctl volume rm
  • :whale: nerdctl volume prune
• Namespace management
  • :nerd_face: nerdctl namespace create
  • :nerd_face: nerdctl namespace inspect
  • :nerd_face: nerdctl namespace ls
  • :nerd_face: nerdctl namespace remove
  • :nerd_face: nerdctl namespace update
• AppArmor profile management
  • :nerd_face: nerdctl apparmor inspect
  • :nerd_face: nerdctl apparmor load
  • :nerd_face: nerdctl apparmor ls
  • :nerd_face: nerdctl apparmor unload
• Builder management
  • :whale: nerdctl builder prune
  • :nerd_face: nerdctl builder debug
• System
  • :whale: nerdctl events
  • :whale: nerdctl info
  • :whale: nerdctl version
  • :whale: nerdctl system prune
• Stats
  • :whale: nerdctl stats
  • :whale: nerdctl top
• Shell completion
  • :nerd_face: nerdctl completion bash
  • :nerd_face: nerdctl completion zsh
  • :nerd_face: nerdctl completion fish
  • :nerd_face: nerdctl completion powershell
• Compose
  • :whale: nerdctl compose
  • :whale: nerdctl compose up
  • :whale: nerdctl compose logs
  • :whale: nerdctl compose build
  • :whale: nerdctl compose create
  • :whale: nerdctl compose exec
  • :whale: nerdctl compose down
  • :whale: nerdctl compose images
  • :whale: nerdctl compose start
  • :whale: nerdctl compose stop
  • :whale: nerdctl compose port
  • :whale: nerdctl compose ps
  • :whale: nerdctl compose pull
  • :whale: nerdctl compose push
  • :whale: nerdctl compose pause
  • :whale: nerdctl compose unpause
  • :whale: nerdctl compose config
  • :whale: nerdctl compose cp
  • :whale: nerdctl compose kill
  • :whale: nerdctl compose restart
  • :whale: nerdctl compose rm
  • :whale: nerdctl compose run
  • :whale: nerdctl compose top
  • :whale: nerdctl compose version
• IPFS management
  • :nerd_face: nerdctl ipfs registry serve
• Global flags
• Unimplemented Docker commands

Container management Copy Chapter

:whale: nerdctl run Copy Section

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 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:<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 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 which is process in containerd by default. process runs process isolated containers. host runs Host Process containers. 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:<container>|ns:|<CNI>): Connect a container to a network.
  • Default: "bridge"
  • container:<name|id>: 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: <name|uid>[:<group|gid>])
• :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 label=<selinuxlabel>: specify custom selinux label
• :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=<CAP>: Add Linux capabilities
• :whale: --cap-drop=<CAP>: 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 <SRC>:<DST>[:<OPT>]: Bind mount a volume, e.g., -v /mnt:/mnt:ro
  • :whale: option rw : Read/Write (when writable)
  • :whale: option ro : Read-only. Recursively read-only (e.g., making children such as /mnt/usb read-only, too) when the kernel and the OCI runtime support it
    (kernel >= 5.12, and runc >= 1.1 or crun >= 1.8.6, as in Docker v25), otherwise non-recursive read-only.
    Use --mount type=bind,...,readonly,bind-recursive=<writable|readonly> to control the recursive read-only mode explicitly.
  • :nerd_face: option rro: Deprecated since the same feature was introduced in Docker v25 with a different syntax; use --mount type=bind,...,readonly,bind-propagation=rprivate,bind-recursive=readonly instead.
    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 runc >= 1.1 or crun >= 1.8.6; an error is raised when the recursive read-only mount is not supported.
  • :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
  • :whale: option z: SELinux shared (multi-category) relabel of the volume content so it can be shared among containers
  • :whale: option Z: SELinux private unshared relabel of the volume content for this container only
    • Requires SELinux on the host and nerdctl started with --selinux-enabled (or selinux_enabled = true in nerdctl.toml).
    • Example: nerdctl run --rm -v /var/data:/data:Z --selinux-enabled IMAGE
• :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 <key>=<value> tuple.
  e.g., -- mount type=bind,source=/src,target=/app,bind-propagation=shared.
  • :whale: type: Current supported mount types are bind, volume, tmpfs, image.
    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
  • 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: mount the filesystem read-only. Recursively read-only when the kernel and the OCI runtime support it
      (kernel >= 5.12, and runc >= 1.1 or crun >= 1.8.6, as in Docker v25). See the bind-recursive option below to control the recursive read-only mode explicitly.
    • :nerd_face: rro: Deprecated since the same feature was introduced in Docker v25 with a different syntax; use readonly with bind-propagation=rprivate and bind-recursive=readonly instead.
      Mount the filesystem recursively read-only.
  • Options specific to bind:
    • :whale: bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default).
    • :whale: bind-recursive: enabled(default), disabled, writable, or readonly.
      • enabled: submounts are recursively bind-mounted, and a readonly mount is recursively read-only when the kernel and the OCI runtime support it.
      • disabled: submounts are not recursively bind-mounted.
      • writable: submounts of a readonly mount are kept writable (the default behavior of Docker until v24).
      • readonly: a readonly mount is forced to be recursively read-only; an error is raised when the kernel or the OCI runtime does not support it.
        Requires bind-propagation=rprivate to be specified in conjunction.
        Whether the OCI runtime supports recursive read-only mounts is detected by running $RUNTIME features, and the result is cached in the XDG cache directory (e.g., ~/.cache/nerdctl/oci-runtime-features).
    • :whale: bind-nonrecursive: true or false(default). Deprecated alias for bind-recursive=disabled / bind-recursive=enabled (removed in Docker v29). If set to true, submounts are not recursively bind-mounted.
    • 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
  • Options specific to image:
    • :whale: src, source: image reference (mandatory).
    • :whale: Currently, the image filesystem is mounted read-only.
    • unimplemented options: image-subpath
• :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: --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=<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=<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=<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
      • :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=<TEMPLATE>: Specify template to set SYSLOG_IDENTIFIER value in journald logs.
    • :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=fluentd: Writes log messages to fluentd. The fluentd daemon must be running on the host machine.
    • The fluentd logging driver supports the following logging options:
      • :whale: --log-opt=fluentd-address=<ADDRESS>: The address of the fluentd daemon, tcp(default) and unix sockets are supported..
      • :whale: --log-opt=fluentd-async=: Enable async mode for fluentd. The default value is false.
      • :whale: --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 1MiB. Accepts human-readable sizes (e.g., 1KiB, 1MiB, 1GiB) or raw byte values. (https://github.com/fluent/fluent-logger-golang/tree/master#bufferlimit)
      • :whale: --log-opt=fluentd-retry-wait=<1s|1ms>: The time to wait before retrying to send logs to fluentd. The default value is 1s.
      • :whale: --log-opt=fluentd-max-retries=<1>: The maximum number of retries to send logs to fluentd. The default value is MaxInt32.
      • :whale: --log-opt=fluentd-sub-second-precision=: Enable sub-second precision for fluentd. The default value is false.
      • :nerd_face: --log-opt=fluentd-async-reconnect-interval=<1s|1ms>: The time to wait before retrying to reconnect to fluentd. The default value is 0s.
      • :nerd_face: --log-opt=fluentd-request-ack=: Enable request ack for fluentd. The default value is false.
  • :whale: --log-driver=syslog: Writes log messages to syslog. The
    syslog daemon must be running on either the host machine or remote.
    • The syslog logging driver supports the following logging options:
      • :whale: --log-opt=syslog-address=<ADDRESS>: The address of an
        external syslog server. The URI specifier may be
        tcp|udp|tcp+tls]://host:port, unix://path, or unixgram://path.
        If the transport is tcp, udp, or tcp+tls, the default port is
        514.
      • :whale: --log-opt=syslog-facility=<FACILITY>: The syslog facility to
        use. Can be the number or name for any valid syslog facility. See the
        syslog documentation.
      • :whale: --log-opt=syslog-tls-ca-cert=<VALUE>: The absolute path to
        the trust certificates signed by the CA. Ignored if the address
        protocol is not tcp+tls.
      • :whale: --log-opt=syslog-tls-cert=<VALUE>: The absolute path to
        the TLS certificate file. Ignored if the address protocol is not
        tcp+tls.
      • :whale: --log-opt=syslog-tls-key=<VALUE>:The absolute path to
        the TLS key file. Ignored if the address protocol is not tcp+tls.
      • :whale: --log-opt=syslog-tls-skip-verify=<VALUE>: If set to true,
        TLS verification is skipped when connecting to the daemon.
        Ignored if the address protocol is not tcp+tls.
      • :whale: --log-opt=syslog-format=<VALUE>: The syslog message format
        to use. If not specified the local UNIX syslog format is used,
        without a specified hostname. Specify rfc3164 for the RFC-3164
        compatible format, rfc5424 for RFC-5424 compatible format, or
        rfc5424micro for RFC-5424 compatible format with microsecond
        timestamp resolution.
      • :whale: --log-opt=tag=<VALUE>: A string that is appended to the
        APP-NAME in the syslog message. By default, nerdctl uses the first
        12 characters of the container ID to tag log messages.
  • :whale: --log-driver=none: Disables logging for the container, preventing log output from being collected.
  • :nerd_face: 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:

• :whale: --ipc=(host|private|shareable|container:<container>): IPC namespace to use and mount /dev/shm. Default: "private". Only implemented on Linux.
• :whale: --shm-size: Size of /dev/shm

GPU flags:

• :whale: --gpus: GPU devices to add to the container ('all' to pass all GPUs). Please see also ./gpu.md for details.

Ulimit flags:

• :whale: --ulimit: Set ulimit

--ulimit can be used to restrict the following types of resources.

Verify flags:

• :nerd_face: --verify: Verify the image (none|cosign|notation). See ./cosign.md and ./notation.md for details.
• :nerd_face: --cosign-key: Path to the public key file, KMS, URI or Kubernetes Secret for --verify=cosign
• :nerd_face: --cosign-certificate-identity: The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows
• :nerd_face: --cosign-certificate-identity-regexp: A regular expression alternative to --cosign-certificate-identity for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows
• :nerd_face: --cosign-certificate-oidc-issuer: The OIDC issuer expected in a valid Fulcio certificate for --verify=cosign,, e.g. https://token.actions.githubusercontent.com or https://oauth2.sigstore.dev/auth. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows
• :nerd_face: --cosign-certificate-oidc-issuer-regexp: A regular expression alternative to --certificate-oidc-issuer for --verify=cosign,. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows

IPFS flags:

• :nerd_face: --ipfs-address: Multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs)

Unimplemented docker run flags:
--device-cgroup-rule, --disable-content-trust,
--health-start-interval, --link*, --storage-opt,
--volume-driver

:whale: nerdctl exec Copy Section

Run a command in a running container.

Usage: nerdctl exec [OPTIONS] CONTAINER COMMAND [ARG...]

Flags:

• :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: -d, --detach: Detached mode: run command in the background
• :whale: -w, --workdir: Working directory inside the container
• :whale: -e, --env: Set environment variables
• :whale: --env-file: Set environment variables from file
• :whale: --privileged: Give extended privileges to the command
• :whale: -u, --user: Username or UID (format: <name|uid>[:<group|gid>])

Unimplemented docker exec flags: --detach-keys

:whale: nerdctl create Copy Section

Create a new container.

Usage: nerdctl create [OPTIONS] IMAGE [COMMAND] [ARG...]

:nerd_face: ipfs:// prefix can be used for IMAGE to pull it from IPFS. See 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.

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.

:whale: nerdctl cp Copy Section

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

Using - as the SRC_PATH streams the contents of STDIN as a tar archive. The command extracts the content of the tar to the DEST_PATH in container's filesystem. In this case, DEST_PATH must specify a directory. Using - as the DEST_PATH streams the contents of the resource as a tar archive to STDOUT.

:warning: 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:

• :whale: -L, --follow-link Always follow symbol link in SRC_PATH.

Unimplemented docker cp flags: --archive

:whale: nerdctl ps Copy Section

List containers.

Usage: nerdctl ps [OPTIONS]

Flags:

• :whale: -a, --all: Show all containers (default shows just running)
• :whale: --no-trunc: Don't truncate output
• :whale: -q, --quiet: Only display container IDs
• :whale: -s, --size: Display total file sizes
• :whale: --format: Format the output using the given Go template
  • :whale: --format=table (default): Table
  • :whale: --format='{{json .}}': JSON
  • :nerd_face: --format=wide: Wide table
  • :nerd_face: --format=json: Alias of --format='{{json .}}'
• :whale: -n, --last: Show n last created containers (includes all states)
• :whale: -l, --latest: Show the latest created container (includes all states)
• :whale: -f, --filter: Filter containers based on given conditions. When specifying the condition 'status', it filters all containers
  • :whale: --filter id=<value>: Container's ID. Both full ID and
    truncated ID are supported
  • :whale: --filter name=<value>: Container's name
  • :whale: --filter label=<key>=<value>: Arbitrary string either a key or a
    key-value pair
  • :whale: --filter exited=<value>: Container's exit code. Only work with
    --all
  • :whale: --filter status=<value>: One of created, running, paused, stopped, exited, pausing, unknown. Note that restarting, removing, dead are
    not supported and will be ignored. When specifying this condition, it filters all containers.
  • :whale: --filter before/since=: Filter containers created before
    or after a given ID or name
  • :whale: --filter volume=<value>: Filter by a given mounted volume or bind
    mount
  • :whale: --filter network=<value>: Filter by a given network

Following arguments for --filter are not supported yet:

1. --filter ancestor=<value>
2. --filter publish/expose=[/]
3. --filter health=<value>
4. --filter isolation=<value>
5. --filter is-task=<value>

:whale: nerdctl inspect Copy Section

Display detailed information on one or more containers.

Usage: nerdctl inspect [OPTIONS] NAME|ID [NAME|ID...]

Flags:

• :nerd_face: --mode=(dockercompat|native): Inspection mode. "native" produces more information.
• :whale: --format: Format the output using the given Go template, e.g, {{json .}}
• :whale: --type: Return JSON for specified type
• :whale: --size: Display total file sizes if the type is container

:whale: nerdctl logs Copy Section

Fetch the logs of a container.

:warning: Currently, only containers created with nerdctl run -d are supported.

Usage: nerdctl logs [OPTIONS] CONTAINER

Flags:

• :whale: --details: Show extra details provided to logs
• :whale: -f, --follow: Follow log output
• :whale: --since: Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)
• :whale: --until: Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)
• :whale: -t, --timestamps: Show timestamps
• :whale: -n, --tail: Number of lines to show from the end of the logs (default "all")

:whale: nerdctl port Copy Section

List port mappings or a specific mapping for the container.

Usage: nerdctl port CONTAINER [PRIVATE_PORT[/PROTO]]

:whale: nerdctl rm Copy Section

Remove one or more containers.

Usage: nerdctl rm [OPTIONS] CONTAINER [CONTAINER...]

Flags:

• :whale: -f, --force: Force the removal of a running|paused|unknown container (uses SIGKILL)
• :whale: -v, --volumes: Remove anonymous volumes associated with the container

Unimplemented docker rm flags: --link

:whale: nerdctl stop Copy Section

Stop one or more running containers.

Usage: nerdctl stop [OPTIONS] CONTAINER [CONTAINER...]

Flags:

• :whale: -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
• :whale: -s, --signal=SIGNAL: Signal to send to the container (e.g. SIGINT).

:whale: nerdctl start Copy Section

Start one or more running containers.

Usage: nerdctl start [OPTIONS] CONTAINER [CONTAINER...]

Flags:

• :whale: -a, --attach: Attach STDOUT/STDERR and forward signals
• :whale: --detach-keys: Override the default detach keys
• :whale: --checkpoint: checkpoint name
• :whale: --detach-keys: checkpoint directory

:whale: nerdctl restart Copy Section

Restart one or more running containers.

Usage: nerdctl restart [OPTIONS] CONTAINER [CONTAINER...]

Flags:

• :whale: -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
• :whale: -s, --signal=SIGNAL: Signal to send to the container (e.g. SIGINT).

:whale: nerdctl update Copy Section

Update configuration of one or more containers.

Usage: nerdctl update [OPTIONS] CONTAINER [CONTAINER...]

• :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: --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: --kernel-memory: Kernel memory limit (deprecated)
• :whale: --pids-limit: Tune container pids limit
• :whale: --blkio-weight: Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)
• :whale: --restart=(no|always|on-failure|unless-stopped): Restart policy to apply when a container exits

:whale: nerdctl wait Copy Section

Block until one or more containers stop, then print their exit codes.

Usage: nerdctl wait CONTAINER [CONTAINER...]

:whale: nerdctl kill Copy Section

Kill one or more running containers.

Usage: nerdctl kill [OPTIONS] CONTAINER [CONTAINER...]

Flags:

• :whale: -s, --signal: Signal to send to the container (default: "KILL")

:whale: nerdctl pause Copy Section

Pause all processes within one or more containers.

Usage: nerdctl pause CONTAINER [CONTAINER...]

:whale: nerdctl unpause Copy Section

Unpause all processes within one or more containers.

Usage: nerdctl unpause CONTAINER [CONTAINER...]

:whale: nerdctl rename Copy Section

Rename a container.

Usage: nerdctl rename CONTAINER NEW_NAME

:whale: nerdctl attach Copy Section

Attach stdin, stdout, and stderr to a running container. For example:

1. nerdctl run -it --name test busybox to start a container with a pty
2. ctrl-p ctrl-q to detach from the container
3. nerdctl attach test to attach to the container

Caveats:

• Currently only one attach session is allowed. When the second session tries to attach, currently no error will be returned from nerdctl.
  However, since behind the scenes, there's only one FIFO for stdin, stdout, and stderr respectively,
  if there are multiple sessions, all the sessions will be reading from and writing to the same 3 FIFOs, which will result in mixed input and partial output.
• Until dual logging (issue #1946) is implemented,
  a container that is spun up by either nerdctl run -d or nerdctl start (without --attach) cannot be attached to.

Usage: nerdctl attach CONTAINER

Flags:

• :whale: --detach-keys: Override the default detach keys
• :whale: --no-stdin: Do not attach STDIN

Unimplemented docker attach flags: --sig-proxy

:whale: nerdctl container prune Copy Section

Remove all stopped containers.

Usage: nerdctl container prune [OPTIONS]

Flags:

• :whale: -f, --force: Do not prompt for confirmation.

Unimplemented docker container prune flags: --filter

:whale: nerdctl diff Copy Section

Inspect changes to files or directories on a container's filesystem

Usage: nerdctl diff CONTAINER

:whale: nerdctl export Copy Section

Export a containers filesystem as a tar archive.

Usage: nerdctl export CONTAINER

Build Copy Chapter

:whale: nerdctl build Copy Section

Build an image from a Dockerfile.

:information_source: Needs buildkitd to be running. See also the document about setting up nerdctl build with BuildKit.

Usage: nerdctl build [OPTIONS] PATH

Flags:

• :nerd_face: --buildkit-host=: BuildKit address
• :whale: -t, --tag: Name and optionally a tag in the 'name:tag' format
• :whale: -f, --file: Name of the Dockerfile
• :whale: --target: Set the target build stage to build
• :whale: --build-arg: Set build-time variables
• :whale: --no-cache: Do not use cache when building the image
• :whale: --output=OUTPUT: Output destination (format: type=local,dest=path)
  • :whale: type=local,dest=path/to/output-dir: Local directory
  • :whale: type=oci[,dest=path/to/output.tar]: Docker/OCI dual-format tar ball (compatible with docker buildx build)
  • :whale: type=docker[,dest=path/to/output.tar]: Docker format tar ball (compatible with docker buildx build)
  • :whale: type=tar[,dest=path/to/output.tar]: Raw tar ball
  • :whale: type=image,name=example.com/image,push=true: Push to a registry (see buildctl build documentation)
• :whale: --progress=(auto|plain|tty): Set type of progress output (auto, plain, tty). Use plain to show container output
• :whale: --provenance: Shorthand for "--attest=type=provenance", see buildx_build.md documentation
• :whale: --pull=(true|false): On true, always attempt to pull latest image version from remote. Default uses buildkit's default.
• :whale: --secret: Secret file to expose to the build: id=mysecret,src=/local/secret
• :whale: --allow: Allow extra privileged entitlement, e.g. network.host, security.insecure (It’s required to configure the buildkitd to enable the feature, see buildkitd.toml documentation)
• :whale: --attest: Attestation parameters (format: "type=sbom,generator=image"), see buildx_build.md documentation
• :whale: --ssh: SSH agent socket or keys to expose to the build (format: default|[=<socket>|<key>[,<key>]])
• :whale: -q, --quiet: Suppress the build output and print image ID on success
• :whale: --sbom: Shorthand for "--attest=type=sbom", see buildx_build.md documentation
• :whale: --cache-from=CACHE: External cache sources (eg. user/app:cache, type=local,src=path/to/dir) (compatible with docker buildx build)
• :whale: --cache-to=CACHE: Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) (compatible with docker buildx build)
• :whale: --platform=(amd64|arm64|...): Set target platform for build (compatible with docker buildx build)
• :whale: --iidfile=FILE: Write the image ID to the file
• :nerd_face: --ipfs: Build image with pulling base images from IPFS. See ipfs.md for details.
• :whale: --label: Set metadata for an image
• :whale: --network=(default|host|none): Set the networking mode for the RUN instructions during build.(compatible with buildctl build)
• :whale: --build-context: Set additional contexts for build (e.g. dir2=/path/to/dir2, myorg/myapp=docker-image://path/to/myorg/myapp)
• :whale: --add-host: Add a custom host-to-IP mapping (format: host:ip)
• :nerd_face: --source-policy-file: BuildKit source policy JSON file for reproducible builds. See BuildKit build-repro docs.
  For compatibility with Docker Buildx, the EXPERIMENTAL_BUILDKIT_SOURCE_POLICY environment variable is also supported. Example no-op policy: {"rules":[]}

Unimplemented docker build flags: --squash

:whale: nerdctl commit Copy Section

Create a new image from a container's changes

Usage: nerdctl commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]

Flags:

• :whale: -a, --author: Author (e.g., "nerdctl contributor [email protected]")
• :whale: -m, --message: Commit message
• :whale: -c, --change: Apply Dockerfile instruction to the created image (supported directives: [CMD, ENTRYPOINT])
• :whale: -p, --pause: Pause container during commit (default: true)
• :nerd_face: --compression: Commit compression algorithm (supported values: zstd or gzip) (default: gzip) (zstd is generally better for compression ratio but might not be as widely supported)
• :nerd_face: --format: Format of the committed image (supported values: docker or oci) (default: docker) (docker uses Docker Schema2 media types for compatibility, oci uses OCI image format media types)
• :nerd_face: --estargz: Convert the committed layer to eStargz for lazy pulling
• :nerd_face: --estargz-compression-level: eStargz compression level (1-9) (default: 9)
• :nerd_face: --estargz-chunk-size: eStargz chunk size
• :nerd_face: --estargz-min-chunk-size: The minimal number of bytes of data must be written in one gzip stream
• :nerd_face: --zstdchunked: Convert the committed layer to zstd:chunked for lazy pulling
  support zstdchunked convert
• :nerd_face: --zstdchunked-compression-level: zstd:chunked compression level (default: 3)
• :nerd_face: --zstdchunked-chunk-size: zstd:chunked chunk size

Image management Copy Chapter

:whale: nerdctl images Copy Section

List images

:warning: The image ID is the OCI digest of the image target (index/manifest). It matches Docker's ID with the containerd image store, but differs from the legacy graphdriver image ID (config digest).

By default (Docker v29 compatible view) the columns are IMAGE, ID, DISK USAGE,
CONTENT SIZE and EXTRA (where U means the image is in use by a container).
Passing --format, --quiet, --no-trunc, --digests or --names falls back to the
legacy table (REPOSITORY, TAG, IMAGE ID, CREATED, PLATFORM, SIZE, BLOB SIZE).

Usage: nerdctl images [OPTIONS] [REPOSITORY[:TAG]]

Flags:

• :whale: -a, --all: Show all images (unimplemented)
• :whale: -q, --quiet: Only show numeric IDs
• :whale: --no-trunc: Don't truncate output
• :whale: --format: Format the output using the given Go template
  • :whale: --format=table: Legacy table (default is the Docker v29 compatible view)
  • :whale: --format='{{json .}}': JSON
  • :nerd_face: --format=wide: Wide table
  • :nerd_face: --format=json: Alias of --format='{{json .}}'
• :whale: --digests: Show digests (compatible with Docker, unlike ID)
• :whale: -f, --filter: Filter the images.
  • :whale: --filter=before=: Images created before given image (exclusive)
  • :whale: --filter=since=: Images created after given image (exclusive)
  • :whale: --filter=label<key>=<value>: Matches images based on the presence of a label alone or a label and a value
  • :whale: --filter=dangling=true: Filter images by dangling
  • :nerd_face: --filter=reference=: Filter images by reference (Matches both docker compatible wildcard pattern and regexp match)
• :nerd_face: --names: Show image names

:whale: nerdctl pull Copy Section

Pull an image from a registry.

Usage: nerdctl pull [OPTIONS] NAME[:TAG|@DIGEST]

:nerd_face: ipfs:// prefix can be used for NAME to pull it from IPFS. See ipfs.md for details.

Flags:

• :whale: --platform=(amd64|arm64|...): Pull content for a specific platform
  • :nerd_face: Unlike Docker, this flag can be specified multiple times (--platform=amd64 --platform=arm64)
• :nerd_face: --all-platforms: Pull content for all platforms
• :nerd_face: --unpack: Unpack the image for the current single platform (auto/true/false)
• :whale: -q, --quiet: Suppress verbose output
• :nerd_face: --verify: Verify the image (none|cosign|notation). See ./cosign.md and ./notation.md for details.
• :nerd_face: --cosign-key: Path to the public key file, KMS, URI or Kubernetes Secret for --verify=cosign
• :nerd_face: --cosign-certificate-identity: The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows
• :nerd_face: --cosign-certificate-identity-regexp: A regular expression alternative to --cosign-certificate-identity for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows
• :nerd_face: --cosign-certificate-oidc-issuer: The OIDC issuer expected in a valid Fulcio certificate for --verify=cosign,, e.g. https://token.actions.githubusercontent.com or https://oauth2.sigstore.dev/auth. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows
• :nerd_face: --cosign-certificate-oidc-issuer-regexp: A regular expression alternative to --certificate-oidc-issuer for --verify=cosign,. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows
• :nerd_face: --ipfs-address: Multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs)
• :nerd_face: --soci-index-digest: Specify a particular index digest for SOCI. If left empty, SOCI will automatically use the index determined by the selection policy.

Unimplemented docker pull flags: --all-tags, --disable-content-trust (default true)

:whale: nerdctl push Copy Section

Push an image to a registry.

Usage: nerdctl push [OPTIONS] NAME[:TAG]

:nerd_face: ipfs:// prefix can be used for NAME to push it to IPFS. See ipfs.md for details.

Flags:

• :nerd_face: --platform=(amd64|arm64|...): Push content for a specific platform
• :nerd_face: --all-platforms: Push content for all platforms
• :whale: -a, --all-tags: Push all tags of an image to the repository. NAME must not contain a tag.
• :nerd_face: --sign: Sign the image (none|cosign|notation). See ./cosign.md and ./notation.md for details.
• :nerd_face: --cosign-key: Path to the private key file, KMS, URI or Kubernetes Secret for --sign=cosign
• :nerd_face: --notation-key-name: Signing key name for a key previously added to notation's key list for --sign=notation
• :nerd_face: --allow-nondistributable-artifacts: Allow pushing images with non-distributable blobs
• :nerd_face: --ipfs-address: Multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs)
• :whale: -q, --quiet: Suppress verbose output
• :nerd_face: --soci-span-size: Span size in bytes that soci index uses to segment layer data. Default is 4 MiB.
• :nerd_face: --soci-min-layer-size: Minimum layer size in bytes to build zTOC for. Smaller layers won't have zTOC and not lazy pulled. Default is 10 MiB.

Unimplemented docker push flags: --disable-content-trust (default true)

:whale: nerdctl load Copy Section

Load an image from a tar archive or STDIN.

:nerd_face: Supports both Docker Image Spec v1.2 and OCI Image Spec v1.0.

Usage: nerdctl load [OPTIONS]

Flags:

• :whale: -i, --input: Read from tar archive file, instead of STDIN
• :whale: -q, --quiet: Suppress the load output
• :nerd_face: --platform=(amd64|arm64|...): Import content for a specific platform
• :nerd_face: --all-platforms: Import content for all platforms

:whale: nerdctl save Copy Section

Save one or more images to a tar archive (streamed to STDOUT by default)

:nerd_face: The archive implements both Docker Image Spec v1.2 and OCI Image Spec v1.0.

Usage: nerdctl save [OPTIONS] IMAGE [IMAGE...]

Flags:

• :whale: -o, --output: Write to a file, instead of STDOUT
• :nerd_face: -q, --quiet: Suppress the progress output
• :nerd_face: --platform=(amd64|arm64|...): Export content for a specific platform
• :nerd_face: --all-platforms: Export content for all platforms

:whale: nerdctl import Copy Section

Import the contents from a tarball to create a filesystem image.

Usage: nerdctl import [OPTIONS] file|URL|- [REPOSITORY[:TAG]]

Flags:

• :whale: -m, --message: Set commit message for imported image
• :nerd_face: --platform=(linux/amd64|linux/arm64|...): Set platform for the imported image

Unimplemented docker import flags: --change

:whale: nerdctl tag Copy Section

Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE.

Usage: nerdctl tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

:whale: nerdctl rmi Copy Section

Remove one or more images

Usage: nerdctl rmi [OPTIONS] IMAGE [IMAGE...]

Flags:

• :nerd_face: --async: Asynchronous mode
• :whale: -f, --force: Force removal of the image

Unimplemented docker rmi flags: --no-prune

:whale: nerdctl image inspect Copy Section

Display detailed information on one or more images.

Usage: nerdctl image inspect [OPTIONS] NAME|ID [NAME|ID...]

Flags:

• :nerd_face: --mode=(dockercompat|native): Inspection mode. "native" produces more information.
• :whale: --format: Format the output using the given Go template, e.g, {{json .}}
• :nerd_face: --platform=(amd64|arm64|...): Inspect a specific platform

:whale: nerdctl image history Copy Section

Show the history of an image.

Usage: nerdctl history [OPTIONS] IMAGE

Flags:

• :whale: --no-trunc: Don't truncate output
• :whale: -q, --quiet: Only display snapshots IDs
• :whale: --format: Format the output using the given Go template, e.g, {{json .}}
• :whale: -H, --human: Print sizes and dates in human readable format (default true)

:whale: nerdctl image prune Copy Section

Remove unused images.

Usage: nerdctl image prune [OPTIONS]

Flags:

• :whale: -a, --all: Remove all unused images, not just dangling ones
• :whale: --filter: Filter the images.
  • :whale: --filter=until=<timestamp>: Images created before given date formatted timestamps or Go duration strings. Currently does not support Unix timestamps.
  • :whale: --filter=label<key>=<value>: Matches images based on the presence of a label alone or a label and a value
• :whale: -f, --force: Do not prompt for confirmation

:nerd_face: nerdctl image convert Copy Section

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> : read ctr-remote optimize --record-out=<FILE> record file. :warning: 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 ./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 ./stargz.md for details). :warning: 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')
• --zstd : Use zstd compression instead of gzip. Should be used in conjunction with '--oci'
• --zstd-compression-level=<LEVEL> : zstd compression level (default: 3)
• --zstdchunked : Use zstd compression instead of gzip (a.k.a zstd:chunked). Should be used in conjunction with '--oci'
• --zstdchunked-record-in=<FILE> : read ctr-remote optimize --record-out=<FILE> record file. :warning: 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
• --overlaybd : convert tar.gz layers to overlaybd layers. Should be used in conjunction with '--oci'
• --overlaybd-fs-type=<TYPE> : filesystem type for overlaybd (default: ext4)
• --overlaybd-dbstr=<STRING> : database config string for overlaybd
• --overlaybd-vsize=<SIZE> : virtual block device size in GB for overlaybd (default: 64)
• --erofs=<MODE> : convert image layers to EROFS media type. Supported values: raw, zstd (see ./erofs.md)
• --erofs-compressors=<COMPRESSORS> : specify mkfs.erofs compressor options, e.g. lz4hc,12
• --erofs-mkfs-options=<OPTIONS> : specify extra mkfs.erofs options, e.g. -T0 --mkfs-time
• --uncompress : convert tar.gz layers to uncompressed tar layers
• --oci : convert Docker media types to OCI media types
• --platform= : convert content for a specific platform
• --all-platforms : convert content for all platforms (default: false)
• --soci : convert content to SOCI image manifest v2
  [Note: soci convert uses the default platform if nothing is specified. --platform flag can be used to specify a platform]
• --soci-span-size : Span size in bytes that soci index uses to segment layer data. Default is 4 MiB.
• --soci-min-layer-size: Minimum layer size in bytes to build zTOC for. Smaller layers won't have zTOC and not lazy pulled. Default is 10 MiB.

:nerd_face: nerdctl image encrypt Copy Section

Encrypt image layers. See ./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

:warning: CAUTION: This command only encrypts image layers, but does NOT encrypt container configuration such as 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>[:] : 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= : Convert content for a specific platform
• --all-platforms : Convert content for all platforms (default: false)

:nerd_face: nerdctl image decrypt Copy Section

Decrypt image layers. See ./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>[:] : 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= : Convert content for a specific platform
• --all-platforms : Convert content for all platforms (default: false)

Checkpoint management Copy Chapter

:whale: nerdctl checkpoint create Copy Section

Create a checkpoint from a running container.

Usage: nerdctl checkpoint create [OPTIONS] CONTAINER CHECKPOINT

Flags:

• :whale: --leave-running: Leave the container running after checkpoint
• :whale: checkpoint-dir: Use a custom checkpoint storage directory

:whale: nerdctl checkpoint list Copy Section

List checkpoints for a container

Usage: nerdctl checkpoint list/ls [OPTIONS] CONTAINER

Flags:

• :whale: checkpoint-dir: Use a custom checkpoint storage directory

:whale: nerdctl checkpoint remove Copy Section

Remove a checkpoint for a container

Usage: nerdctl checkpoint remove/rm [OPTIONS] CONTAINER CHECKPOINT

Flags:

• :whale: checkpoint-dir: Use a custom checkpoint storage directory

Manifest management Copy Chapter

:whale: nerdctl manifest annotate Copy Section

Add additional information to a local image manifest.

Usage: nerdctl manifest annotate [OPTIONS] INDEX/MANIFESTLIST MANIFEST

Flags:

• :whale: --os: Set operating system (e.g., "linux", "windows", "freebsd")
• :whale: --arch: Set architecture (e.g., "amd64", "arm64", "arm")
• :whale: --os-version: Set operating system version (e.g., "10.0.19041")
• :whale: --variant: Set architecture variant (e.g., "v7", "v8")
• :whale: --os-features: Set operating system features (e.g., "win32k")

Examples:

nerdctl manifest annotate myapp:latest alpine@sha256:eafc1edb577d2e9b458664a15f23ea1c370214193226069eb22921169fc7e43f \
  --os linux --arch arm --variant v7 --os-features feature1,feature2

:whale: nerdctl manifest create Copy Section

Create a local index/manifest list.

Usage: nerdctl manifest create [OPTIONS] INDEX/MANIFESTLIST MANIFEST [MANIFEST...]

Flags:

• --amend: Amend the existing index/manifest list
• --insecure: Allow communication with an insecure registry

Example:

nerdctl manifest create myapp:latest alpine@sha256:eafc1edb577d2e9b458664a15f23ea1c370214193226069eb22921169fc7e43f

:whale: nerdctl manifest inspect Copy Section

Display the contents of a manifest list or manifest.

Usage: nerdctl manifest inspect [OPTIONS] MANIFEST

Input formats

You can specify the manifest to inspect using one of the following formats:

• Image name with tag: alpine:3.22.1
• Image name with digest: alpine@sha256:eafc1edb577d2e9b458664a15f23ea1c370214193226069eb22921169fc7e43f

Flags:

• --verbose : Verbose output, show additional info including layers and platform
• --insecure: Allow communication with an insecure registry
  Example:

nerdctl manifest inspect alpine:3.22.1
nerdctl manifest inspect alpine@sha256:eafc1edb577d2e9b458664a15f23ea1c370214193226069eb22921169fc7e43f

:whale: nerdctl manifest push Copy Section

Push a manifest list to a registry.

Usage: nerdctl manifest push [OPTIONS] INDEX/MANIFESTLIST

Flags:

• --insecure: Allow communication with an insecure registry
• --purge: Remove the manifest list after pushing

Examples:

# Push a manifest list to a registry
nerdctl manifest push myapp:latest

:whale: nerdctl manifest rm Copy Section

Remove one or more index/manifest lists.

Usage: nerdctl manifest rm INDEX/MANIFESTLIST [INDEX/MANIFESTLIST...]

Example:

nerdctl manifest rm alpine:3.22.1 alpine:3.22.2

Registry Copy Chapter

:whale: nerdctl login Copy Section

Log in to a container registry.

Usage: nerdctl login [OPTIONS] [SERVER]

Flags:

• :whale: -u, --username: Username
• :whale: -p, --password: Password
• :whale: --password-stdin: Take the password from stdin

:whale: nerdctl logout Copy Section

Log out from a container registry

Usage: nerdctl logout [SERVER]

:whale: nerdctl search Copy Section

Search Docker Hub or a registry for images

Usage: nerdctl search [OPTIONS] TERM

Flags:

• :whale: --limit: Max number of search results (default: 0)
• :whale: --no-trunc: Don't truncate output (default: false)
• :whale: --filter, -f: Filter output based on conditions provided
• :whale: --format: Format the output using the given Go template

Network management Copy Chapter

:whale: nerdctl network create Copy Section

Create a network

:information_source: To isolate CNI bridge, CNI plugins v1.1.0 or later needs to be installed.

Usage: nerdctl network create [OPTIONS] NETWORK

Flags:

• :whale: -d, --driver=(bridge|nat|macvlan|ipvlan): Driver to manage the Network
  • :whale: --driver=bridge: Default driver for unix
  • :whale: --driver=macvlan: Macvlan network driver for unix
  • :whale: --driver=ipvlan: IPvlan network driver for unix
  • :whale: --driver=nat: Default driver for windows
• :whale: -o, --opt: Set driver specific options
  • :whale: --opt=com.docker.network.driver.mtu=<MTU>: Set the containers network MTU
  • :nerd_face: --opt=mtu=<MTU>: Alias of --opt=com.docker.network.driver.mtu=<MTU>
  • :whale: --opt=com.docker.network.bridge.enable_icc=: Enable or Disable inter-container connectivity
  • :nerd_face: --opt=icc=: Alias of --opt=com.docker.network.bridge.enable_icc
  • :whale: --opt=macvlan_mode=(bridge)>: Set macvlan network mode (default: bridge)
  • :whale: --opt=ipvlan_mode=(l2|l3): Set IPvlan network mode (default: l2)
  • :nerd_face: --opt=mode=(bridge|l2|l3): Alias of --opt=macvlan_mode=(bridge) and --opt=ipvlan_mode=(l2|l3)
  • :whale: --opt=parent=: Set valid parent interface on host
• :whale: --ipam-driver=(default|host-local|dhcp): IP Address Management Driver
  • :whale: --ipam-driver=default: Default IPAM driver
  • :nerd_face: --ipam-driver=host-local: Host-local IPAM driver for unix
  • :nerd_face: --ipam-driver=dhcp: DHCP IPAM driver for unix, requires root
• :whale: --ipam-opt: Set IPAM driver specific options
• :whale: --subnet: Subnet in CIDR format that represents a network segment, e.g. "10.5.0.0/16"
• :whale: --gateway: IPv4 or IPv6 Gateway for the master subnet
• :whale: --ip-range: Allocate container ip from a sub-range
• :whale: --aux-address: Auxiliary IPv4 or IPv6 addresses, as name=IP pairs. Each IP is reserved and never assigned to a container. Repeatable, and matched to the subnet that contains it.
• :whale: --label: Set metadata on a network
• :whale: --ipv4: Enable IPv4. Enabled by default; set to false with --ipv6 and an IPv6 subnet for an IPv6-only network. --ipv4=false is not supported on Windows.
• :whale: --ipv6: Enable IPv6. Should be used with a valid subnet.
• :whale: --internal: Restrict external access to the network.

Unimplemented docker network create flags: --attachable, --config-from, --config-only, --ingress, --scope

:whale: nerdctl network ls Copy Section

List networks

Usage: nerdctl network ls [OPTIONS]

Flags:

• :whale: -q, --quiet: Only display network IDs
• :whale: --format: Format the output using the given Go template
  • :whale: --format=table (default): Table
  • :whale: --format='{{json .}}': JSON
  • :nerd_face: --format=wide: Alias of --format=table
  • :nerd_face: --format=json: Alias of --format='{{json .}}'

Unimplemented docker network ls flags: --no-trunc

:whale: nerdctl network inspect Copy Section

Display detailed information on one or more networks

Usage: nerdctl network inspect [OPTIONS] NETWORK [NETWORK...]

Flags:

• :whale: --format: Format the output using the given Go template, e.g, {{json .}}
• :nerd_face: --mode=(dockercompat|native): Inspection mode. "native" produces more information.

Unimplemented docker network inspect flags: --verbose

:whale: nerdctl network rm Copy Section

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...]

:whale: nerdctl network prune Copy Section

Remove all unused networks

Usage: nerdctl network prune [OPTIONS]

Flags:

• :whale: -f, --force: Do not prompt for confirmation

Unimplemented docker network prune flags: --filter

Volume management Copy Chapter

:whale: nerdctl volume create Copy Section

Create a volume

Usage: nerdctl volume create [OPTIONS] [VOLUME]

Flags:

• :whale: --label: Set metadata for a volume

Unimplemented docker volume create flags: --driver, --opt

:whale: nerdctl volume ls Copy Section

List volumes

Usage: nerdctl volume ls [OPTIONS]

Flags:

• :whale: -q, --quiet: Only display volume names
• :whale: --format: Format the output using the given Go template
  • :whale: --format=table (default): Table
  • :whale: --format='{{json .}}': JSON
  • :nerd_face: --format=wide: Alias of --format=table
  • :nerd_face: --format=json: Alias of --format='{{json .}}'
• :nerd_face: --size: Display the disk usage of volumes.
• :whale: -f, --filter: Filter volumes based on given conditions.
  • :whale: --filter label=<key>=<value>: Matches volumes by label on both
    key and value. If value is left empty, matches all volumes with key
    regardless of its value
  • :whale: --filter name=<value>: Matches all volumes with a name containing
    the value string
  • :nerd_face: --filter "size=<value>": Matches all volumes with a size
    meets the value. size operand can be >=, <=, >, <, = and value must be
    an integer. Quotes should be used otherwise some shells may treat operand as
    redirections

Following arguments for --filter are not supported yet:

1. --filter=dangling=true: Filter volumes by dangling
2. --filter=driver=local: Filter volumes by driver

:whale: nerdctl volume inspect Copy Section

Display detailed information on one or more volumes

Usage: nerdctl volume inspect [OPTIONS] VOLUME [VOLUME...]

Flags:

• :whale: --format: Format the output using the given Go template, e.g, {{json .}}
• :nerd_face: --size: Displays disk usage of volume

:whale: nerdctl volume rm Copy Section

Remove one or more volumes

Usage: nerdctl volume rm [OPTIONS] VOLUME [VOLUME...]

• :whale: -f, --force: Force the removal of one or more volumes

:whale: nerdctl volume prune Copy Section

Remove all unused local volumes

Usage: nerdctl volume prune [OPTIONS]

Flags:

• :whale: -f, --force: Do not prompt for confirmation

Unimplemented docker volume prune flags: --filter

Namespace management Copy Chapter

:nerd_face: nerdctl namespace create Copy Section

Create a new namespace.

Usage: nerdctl namespace create NAMESPACE
Flags:

• --label: Set labels for a namespace

:nerd_face: nerdctl namespace inspect Copy Section

Inspect a namespace.

Usage: nerdctl namespace inspect NAMESPACE

:nerd_face: nerdctl namespace ls Copy Section

List containerd namespaces such as "default", "moby", or "k8s.io".

Usage: nerdctl namespace ls [OPTIONS]

Flags:

• -q, --quiet: Only display namespace names
• -f, --format: Format the output using the given Go template, e.g, {{json .}}

:nerd_face: nerdctl namespace remove Copy Section

Remove one or more namespaces.

Usage: nerdctl namespace remove [OPTIONS] NAMESPACE [NAMESPACE...]

Flags:

• -c, --cgroup: delete the namespace's cgroup

:nerd_face: nerdctl namespace update Copy Section

Update labels for a namespace.

Usage: nerdctl namespace update NAMESPACE

Flags:

• --label: Set labels for a namespace

AppArmor profile management Copy Chapter

:nerd_face: nerdctl apparmor inspect Copy Section

Display the default AppArmor profile "nerdctl-default". Other profiles cannot be displayed with this command.

Usage: nerdctl apparmor inspect

:nerd_face: nerdctl apparmor load Copy Section

Load the default AppArmor profile "nerdctl-default". Requires root.

Usage: nerdctl apparmor load

:nerd_face: nerdctl apparmor ls Copy Section

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 .}}

:nerd_face: nerdctl apparmor unload Copy Section

Unload an AppArmor profile. The target profile name defaults to "nerdctl-default". Requires root.

Usage: nerdctl apparmor unload [PROFILE]

Builder management Copy Chapter

:whale: nerdctl builder prune Copy Section

Clean up BuildKit build cache.

:warning: The output format is not compatible with Docker.

Usage: nerdctl builder prune

Flags:

• :nerd_face: --buildkit-host=: BuildKit address
• :whale: --all: Remove all unused build cache, not just dangling ones
• :whale: --force: Do not prompt for confirmation

Unimplemented docker builder prune flags: --filter, --keep-storage

:nerd_face: nerdctl builder debug Copy Section

Interactive debugging of Dockerfile using buildg.
Please refer to ./builder-debug.md for details.
This is an experimental feature.

:warning: This command currently doesn't use the host's buildkitd daemon but uses the patched version of BuildKit provided by buildg. This should be fixed in the future.

:warning: This command is currently incompatible with docker buildx debug.

Usage: nerdctl builder debug PATH

Flags:

• :nerd_face: -f, --file: Name of the Dockerfile
• :nerd_face: --image: Image to use for debugging stage
• :nerd_face: --target: Set the target build stage to build
• :nerd_face: --build-arg: Set build-time variables

System Copy Chapter

:whale: nerdctl events Copy Section

Get real time events from the server.

:warning: The output format is not compatible with Docker.

Usage: nerdctl events [OPTIONS]

Flags:

• :whale: --format: Format the output using the given Go template, e.g, {{json .}}
• :whale: -f, --filter: Filter containers based on given conditions
  • :whale: --filter event=<value>: Event's status. Start is the only supported status.

Unimplemented docker events flags: --since, --until

:whale: nerdctl info Copy Section

Display system-wide information

Usage: nerdctl info [OPTIONS]

Flags:

• :whale: -f, --format: Format the output using the given Go template, e.g, {{json .}}
• :nerd_face: --mode=(dockercompat|native): Information mode. "native" produces more information.

:whale: nerdctl version Copy Section

Show the nerdctl version information

Usage: nerdctl version [OPTIONS]

Flags:

• :whale: -f, --format: Format the output using the given Go template, e.g, {{json .}}

:whale: nerdctl system prune Copy Section

Remove unused data

Usage: nerdctl system prune [OPTIONS]

Flags:

• :whale: -a, --all: Remove all unused images, not just dangling ones
• :whale: -f, --force: Do not prompt for confirmation
• :whale: --volumes: Prune volumes

Unimplemented docker system prune flags: --filter

Stats Copy Chapter

:whale: nerdctl stats Copy Section

Display a live stream of container(s) resource usage statistics.

Usage: nerdctl stats [OPTIONS]

Flags:

• :whale: -a, --all: Show all containers (default shows just running)
• :whale: --format=FORMAT: Pretty-print images using a Go template, e.g., {{json .}}
• :whale: --no-stream: Disable streaming stats and only pull the first result
• :whale: --no-trunc: Do not truncate output

:whale: nerdctl top Copy Section

Display the running processes of a container.

Usage: nerdctl top CONTAINER [ps OPTIONS]

Shell completion Copy Chapter

:nerd_face: nerdctl completion bash Copy Section

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.

:nerd_face: nerdctl completion zsh Copy Section

Generate the autocompletion script for zsh.

Usage: see nerdctl completion zsh --help

:nerd_face: nerdctl completion fish Copy Section

Generate the autocompletion script for fish.

Usage: see nerdctl completion fish --help

:nerd_face: nerdctl completion powershell Copy Section

Generate the autocompletion script for powershell.

Usage: see nerdctl completion powershell --help

Compose Copy Chapter

:whale: nerdctl compose Copy Section

Compose

Usage: nerdctl compose [OPTIONS] [COMMAND]

Flags:

• :whale: -f, --file: Specify an alternate compose file
• :whale: -p, --project-name: Specify an alternate project name
• :whale: --project-directory: Specify an alternate working directory
• :nerd_face: --ipfs-address: Multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs)
• :whale: `--profile: Specify a profile to enable
• :whale: --env-file : Specify an alternate environment file

:whale: nerdctl compose up Copy Section

Create and start containers

Usage: nerdctl compose up [OPTIONS] [SERVICE...]

Flags:

• :whale: --abort-on-container-exit: Stops all containers if any container was stopped. Incompatible with -d.
• :whale: -d, --detach: Detached mode: Run containers in the background. Incompatible with --abort-on-container-exit.
• :whale: --no-build: Don't build an image, even if it's missing.
• :whale: --no-color: Produce monochrome output
• :whale: --no-log-prefix: Don't print prefix in logs
• :whale: --build: Build images before starting containers.
• :nerd_face: --ipfs: Build images with pulling base images from IPFS. See ipfs.md for details.
• :whale: --quiet-pull: Pull without printing progress information
• :whale: --scale: Scale SERVICE to NUM instances. Overrides the scale setting in the Compose file if present.
• :whale: --remove-orphans: Remove containers for services not defined in the Compose file
• :whale: --force-recreate: force Compose to stop and recreate all containers
• :whale: --no-recreate: force Compose to reuse existing containers
• :whale: --pull: Pull image before running ("always"|"missing"|"never")

Unimplemented docker-compose up (V1) flags: --no-deps, --always-recreate-deps,
--no-start, --attach-dependencies, --timeout, --renew-anon-volumes, --exit-code-from

Unimplemented docker compose up (V2) flags: --environment

:whale: nerdctl compose logs Copy Section

Show logs of running containers

Usage: nerdctl compose logs [OPTIONS] [SERVICE...]

Flags:

• :whale: --no-color: Produce monochrome output
• :whale: --no-log-prefix: Don't print prefix in logs
• :whale: -f, --follow: Follow log output.
• :whale: --timestamps: Show timestamps
• :whale: --tail: Number of lines to show from the end of the logs

Unimplemented docker compose logs (V2) flags: --since, --until

:whale: nerdctl compose build Copy Section

Build or rebuild services.

Usage: nerdctl compose build [OPTIONS] [SERVICE...]

Flags:

• :whale: --build-arg: Set build-time variables for services
• :whale: --no-cache: Do not use cache when building the image
• :whale: --progress: Set type of progress output (auto, plain, tty). Use plain to show container output
• :nerd_face: --ipfs: Build images with pulling base images from IPFS. See ipfs.md for details.

Unimplemented docker-compose build (V1) flags: --compress, --force-rm, --memory, --no-rm, --parallel, --pull, --quiet

:whale: nerdctl compose create Copy Section

Creates containers for one or more services.

Usage: nerdctl compose create [OPTIONS] [SERVICE...]

Flags:

• :whale: --build: Build images before starting containers
• :whale: --force-recreate: Recreate containers even if their configuration and image haven't changed
• :whale: --no-build: Don't build an image even if it's missing, conflict with --build
• :whale: --no-recreate: Don't recreate containers if they exist, conflict with --force-recreate
• :whale: --pull: Pull images before running. (support always|missing|never) (default "missing")

:whale: nerdctl compose exec Copy Section

Execute a command on a running container of the service.

Usage: nerdctl compose exec [OPTIONS] SERVICE COMMAND [ARGS...]

Flags:

• :whale: -d, --detach: Detached mode: Run the command in background
• :whale: -e, --env: Set environment variables
• :whale: --index: Set index of the container if the service has multiple instances. (default 1)
• :whale: -i, --interactive: Keep STDIN open even if not attached (default true)
• :whale: --privileged: Give extended privileges to the command
• :whale: -t, --tty: Allocate a pseudo-TTY
• :whale: -T, --no-TTY: Disable pseudo-TTY allocation. By default nerdctl compose exec allocates a TTY.
• :whale: -u, --user: Username or UID (format: <name|uid>[:<group|gid>])
• :whale: -w, --workdir: Working directory inside the container

:whale: nerdctl compose down Copy Section

Remove containers and associated resources

Usage: nerdctl compose down [OPTIONS]

Flags:

• :whale: -v, --volumes: Remove named volumes declared in the volumes section of the Compose file and anonymous volumes attached to containers
• :whale: --remove-orphans: Remove containers of services not defined in the Compose file.

Unimplemented docker-compose down (V1) flags: --rmi, --timeout

:whale: nerdctl compose images Copy Section

List images used by created containers in services

Usage: nerdctl compose images [OPTIONS] [SERVICE...]

Flags:

• :whale: -q, --quiet: Only show numeric image IDs
• :whale: --format: Format the output. Supported values: [json]

:whale: nerdctl compose start Copy Section

Start existing containers for service(s)

Usage: nerdctl compose start [SERVICE...]

:whale: nerdctl compose stop Copy Section

Stop containers in services without removing them.

Usage: nerdctl compose stop [OPTIONS] [SERVICE...]

Flags:

• :whale: -t, --timeout: Seconds to wait for stop before killing it (default 10)

:whale: nerdctl compose port Copy Section

Print the public port for a port binding of a service container

Usage: nerdctl compose port [OPTIONS] SERVICE PRIVATE_PORT

Flags:

• :whale: --index: Index of the container if the service has multiple instances. (default 1)
• :whale: --protocol: Protocol of the port (tcp|udp) (default "tcp")

:whale: nerdctl compose ps Copy Section

List containers of services

Usage: nerdctl compose ps [OPTIONS] [SERVICE...]

• :whale: -a, --all: Show all containers (default shows just running)
• :whale: -q, --quiet: Only display container IDs
• :whale: --format: Format the output
  • :whale: --format=table (default): Table
  • :whale: --format=json': JSON
• :whale: -f, --filter: Filter containers based on given conditions
  • :whale: --filter status=<value>: One of created, running, paused, restarting, exited, pausing, unknown. Note that removing, dead are
    not supported and will be ignored
• :whale: --services: Print the service names, one per line
• :whale: --status: Filter containers by status. Values: [paused | restarting | running | created | exited | pausing | unknown]

:whale: nerdctl compose pull Copy Section

Pull service images

Usage: nerdctl compose pull [OPTIONS] [SERVICE...]

Flags:

• :whale: -q, --quiet: Pull without printing progress information

Unimplemented docker-compose pull (V1) flags: --ignore-pull-failures, --parallel, --no-parallel, include-deps

:whale: nerdctl compose push Copy Section

Push service images

Usage: nerdctl compose push [OPTIONS] [SERVICE...]

Unimplemented docker-compose push (V1) flags: --ignore-push-failures

:whale: nerdctl compose pause Copy Section

Pause all processes within containers of service(s). They can be unpaused with nerdctl compose unpause

Usage: nerdctl compose pause [SERVICE...]

:whale: nerdctl compose unpause Copy Section

Unpause all processes within containers of service(s)

Usage: nerdctl compose unpause [SERVICE...]

:whale: nerdctl compose config Copy Section

Validate and view the Compose file

Usage: nerdctl compose config

Flags:

• :whale: -q, --quiet: Pull without printing progress information
• :whale: --services: Print the service names, one per line.
• :whale: --volumes: Print the volume names, one per line.
• :whale: --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

:whale: nerdctl compose cp Copy Section

Copy files/folders between a service container and the local filesystem

Usage:

nerdctl compose cp [OPTIONS] SERVICE:SRC_PATH DEST_PATH|-
nerdctl compose cp [OPTIONS] SRC_PATH|- SERVICE:DEST_PATH [flags]

Flags:

• :whale: --dry-run: Execute command in dry run mode
• :whale: -L, --follow-link: Always follow symbol link in SRC_PATH
• :whale: --index int: index of the container if service has multiple replicas

Unimplemented docker compose cp flags: --archive

:whale: nerdctl compose kill Copy Section

Force stop service containers

Usage: nerdctl compose kill [OPTIONS] [SERVICE...]

Flags:

• :whale: -s, --signal: SIGNAL to send to the container (default: "SIGKILL")

:whale: nerdctl compose restart Copy Section

Restart containers of given (or all) services

Usage: nerdctl compose restart [OPTIONS] [SERVICE...]

Flags:

• :whale: -t, --timeout: Seconds to wait before restarting it (default 10)

:whale: nerdctl compose rm Copy Section

Remove stopped service containers

Usage: nerdctl compose rm [OPTIONS] [SERVICE...]

Flags:

• :whale: -f, --force: Don't prompt for confirmation (different with -f in nerdctl rm which means force deletion).
• :whale: -s, --stop: Stop containers before removing.
• :whale: -v, --volumes: Remove anonymous volumes associated with the container.

:whale: nerdctl compose run Copy Section

Run a one-off command on a service

Usage: nerdctl compose run [OPTIONS] SERVICE [COMMAND] [ARGS...]

Flags:

• :whale: --build: Build images before starting containers.
• :whale: -d, —detach: Detached mode: Run containers in the background.
• :whale: --entrypoint: Overwrite the default ENTRYPOINT of the image.
• :whale: -e, —env: Set environment variables.
• :whale: -i, —interactive: Keep STDIN open even if not attached (default true).
• :whale: -l, —label: Set metadata on container.
• :whale: --name: Assign a name to the container.
• :whale: --no-build: Don't build an image, even if it's missing.
• :whale: --no-color: Produce monochrome output.
• :whale: --no-deps: Don't start dependencies.
• :whale: --no-log-prefix: Don't print prefix in logs.
• :whale: --publish: Publish a container's port(s) to the host.
• :whale: --quiet-pull: Pull without printing progress information.
• :whale: --remove-orphans: Remove containers for services not defined in the Compose file.
• :whale: --rm: Automatically remove the container when it exits.
• :whale: --service-ports: Run command with the service's ports enabled and mapped to the host.
• :whale: -u, —user: Username or UID (format: <name|uid>[:<group|gid>]).
• :whale: -v, —volume: Bind mount a volume.
• :whale: -w, —workdir: Working directory inside the container.

Unimplemented docker-compose run (V1) flags: --use-aliases, --no-TTY

Unimplemented docker compose run (V2) flags: --use-aliases, --no-TTY, --tty

:whale: nerdctl compose top Copy Section

Display the running processes of service containers

Usage: nerdctl compose top [SERVICES...]

:whale: nerdctl compose version Copy Section

Show the Compose version information (which is the nerdctl version)

Usage: nerdctl compose version

Flags:

• :whale: -f, --format: Format the output. Values: [pretty | json] (default "pretty")
• :whale: --short: Shows only Compose's version number

IPFS management Copy Chapter

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.

:nerd_face: nerdctl ipfs registry serve Copy Section

Serve read-only registry backed by IPFS on localhost.
This is needed to run nerdctl build with pulling base images from IPFS.
Other commands (e.g. nerdctl push ipfs:// and nerdctl pull ipfs://<CID>) don't require this.

You need to install ipfs command on the host.
See ipfs.md for details.

Usage: nerdctl ipfs registry serve [OPTIONS]

Flags:

• :nerd_face: --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).
• :nerd_face: --listen-registry: Address to listen (default localhost:5050).
• :nerd_face: --read-retry-num: Times to retry query on IPFS (default 0 (no retry))
• :nerd_face: --read-timeout: Timeout duration of a read request to IPFS (default 0 (no timeout))

Global flags Copy Chapter

• :nerd_face: --address: containerd address, optionally with "unix://" prefix
• :nerd_face: -a, --host, -H: deprecated aliases of --address
• :nerd_face: --namespace: containerd namespace
• :nerd_face: -n: deprecated alias of --namespace
• :nerd_face: --snapshotter: containerd snapshotter
• :nerd_face: --storage-driver: deprecated alias of --snapshotter
• :nerd_face: --cni-path: CNI binary path (default: /opt/cni/bin) [$CNI_PATH]
• :nerd_face: --cni-netconfpath: CNI netconf path (default: /etc/cni/net.d) [$NETCONFPATH]
• :nerd_face: --data-root: nerdctl data root, e.g. "/var/lib/nerdctl"
• :nerd_face: --cgroup-manager=(cgroupfs|systemd|none): cgroup manager
  • Default: "systemd" on cgroup v2 (rootful & rootless), "cgroupfs" on v1 rootful, "none" on v1 rootless
• :nerd_face: --insecure-registry: skips verifying HTTPS certs, and allows falling back to plain HTTP
• :nerd_face: --host-gateway-ip: IP address that the special 'host-gateway' string in --add-host resolves to. It has no effect without setting --add-host
  • Default: the IP address of the host
• :nerd_face: --userns-remap=:<groupname>: Support idmapping of containers. This options is only supported on rootful linux for container create and run if a user name and optionally group name is passed, it does idmapping based on the uidmap and gidmap ranges specified in /etc/subuid and /etc/subgid respectively. Note: --userns-remap is not supported for building containers. Nerdctl Build doesn't support userns-remap feature. (format: <name|uid>[:<group|gid>])
• :nerd_face: --selinux-enabled: Enable selinux support

The global flags can be also specified in /etc/nerdctl/nerdctl.toml (rootful) and ~/.config/nerdctl/nerdctl.toml (rootless).
See ./config.md.

Unimplemented Docker commands Copy Chapter

Image:

• docker trust * (Instead, nerdctl supports nerdctl pull --verify=cosign|notation and nerdctl push --sign=cosign|notation. See ./cosign.md and ./notation.md.)

Network management:

• docker network connect
• docker network disconnect

Compose:

• docker compose attach
• docker compose events
• docker compose ls
• docker compose scale
• docker compose stats
• docker compose wait
• docker compose watch

Builder:

• docker buildx debug (buildx debugger)

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 *

File: docs/compose.md Copy Chapter

nerdctl compose

Usage Copy Chapter

The nerdctl compose CLI is designed to be compatible with docker-compose.

$ nerdctl compose up -d
$ nerdctl compose down

See the Command Reference in ../README.md.

Spec conformance Copy Chapter

nerdctl compose implements The Compose Specification,
which was derived from Docker Compose file version 3 specification.

Unimplemented YAML fields Copy Section

• Fields that correspond to unimplemented docker run flags, e.g., services.<SERVICE>.links (corresponds to docker run --link)
• Fields that correspond to unimplemented docker build flags, e.g., services.<SERVICE>.build.extra_hosts (corresponds to docker build --add-host)
• services.<SERVICE>.credential_spec
• services.<SERVICE>.deploy.update_config
• services.<SERVICE>.deploy.rollback_config
• services.<SERVICE>.deploy.resources.reservations
• services.<SERVICE>.deploy.placement
• services.<SERVICE>.deploy.endpoint_mode
• services.<SERVICE>.healthcheck.start_interval
• services.<SERVICE>.stop_grace_period
• services.<SERVICE>.stop_signal
• configs.<CONFIG>.external
• secrets.<SECRET>.external

Incompatibility Copy Section

`services..build.context`

• The value must be a local directory path, not a URL.

`services..secrets`, `services..configs`

• uid, gid: Cannot be specified. The default value is not propagated from USER instruction of Dockerfile.
  The file owner corresponds to the original file on the host.
• mode: Cannot be specified. The file is mounted as read-only, with permission bits that correspond to the original file on the host.