--- schema_version: 1 route: /t/nerdctl.md tool: "nerdctl" --- # sincecutoff.com /t/nerdctl — nerdctl - name: nerdctl - kind: cli - children: none - homepage: Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows. Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json). To stay current, read the changes feed: [`/v1/changes.md?tool=nerdctl`](https://sincecutoff.com/v1/changes.md?tool=nerdctl) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt). ### nerdctl compose supports image volumes (2026-09-20) - slug: nerdctl-compose-supports-image-volumes-15834bd69af9 - score: 0.96 How to use it: When a Compose service needs to mount an image, set its volume `type` to `image` and specify the image reference and mount target. Run `nerdctl compose up` to create and start the project. Examples: ``` services: : volumes: - type: image source: target: # From the Compose project directory: nerdctl compose up ``` - why_it_matters: Maintain a Compose project that mounts an image volume. - sources: , - gotchas: "Version: v2.4.0"; "services..volumes[].type (required): Set to `image` for an image volume."; "services..volumes[].source (required): Image reference used as the mount source."; "services..volumes[].target (required): Container path where the image is mounted; the v2.4.0 Compose image-volume docs do not describe this field."; "services..volumes[].image.subpath: Not supported in v2.4.0."; "Prerequisite: Use nerdctl v2.4.0 or later for the released image-volume support."; "Prerequisite: nerdctl Compose is documented as requiring nerdctl >= 0.8." ### nerdctl container mounts images and image subpaths read-only (2026-09-20) - slug: nerdctl-container-mounts-images-and-image-subpaths-read-only-2777ff956b70 - score: 0.91 How to use it: When running a container with read-only access to an image, use `nerdctl run` with `--mount type=image,src=,target=`. To mount a relative path within the image rootfs, add `image-subpath=`; the image filesystem is read-only. Examples: ``` nerdctl run --rm --mount type=image,src=,target=

``` ``` nerdctl run --rm --mount type=image,src=,target=,image-subpath=

``` - why_it_matters: Run a container with read-only access to an image or a path inside its root filesystem. - sources: , - gotchas: "Version: v2.4.0"; "--mount (required): Attach a filesystem mount; provide comma-separated key=value pairs."; "type=image (required): Selects an image filesystem mount."; "src (or source) (required): Image reference to mount."; "target (or dst, destination) (required): Destination path in the container for the mount."; "image-subpath: Relative path inside the image rootfs to mount instead of the whole rootfs. Must resolve inside rootfs; empty, absolute, escaping, and paths through absolute symlinks are rejected. `.` mounts the whole rootfs."; " (required): Image argument for the container to run."; "Prerequisite: This nerdctl release is expected to be used with containerd v1.7 or later; some features may not work with other containerd releases."; "The image mount is read-only." ### nerdctl container run adds --expose and --publish-all (2026-09-20) - slug: nerdctl-container-run-adds-expose-and-publish-all-31693362a946 - score: 0.92 How to use it: When running a container, use `--expose` to declare ports or `--publish-all` (`-P`) to publish exposed ports. The v2.4.0 release note confirms both flags were added; the v2.4.0 command reference does not document their syntax or behavior. - why_it_matters: Configure exposed or automatically published container ports when running a container. - sources: - gotchas: "Version: v2.4.0"; "Prerequisite: nerdctl v2.4.0 release expects containerd v1.7 or later; some features may not work with other releases." ### nerdctl events supports label-based filtering (2026-09-20) - slug: nerdctl-events-supports-label-based-filtering-97356c0ceea4 - score: 0.97 How to use it: When debugging containers with a specific label, follow the event stream with `nerdctl events --filter label=com.example.app=myapp`. Label filtering is available in nerdctl v2.4.0. Examples: ``` nerdctl events --filter label=com.example.app=myapp ``` - why_it_matters: Follow events for containers with a specific label during debugging. - before: Before v2.4.0, `nerdctl events` did not support label-based filtering. - sources: , , - gotchas: "Version: v2.4.0"; "--filter (-f): Filter events by a condition; for this task, use `label==`."; "label== (required): Match events for containers with the specified label key and value. The value may contain `=` characters."; "Prerequisite: Use nerdctl v2.4.0 or later for label-based event filtering."; "Prerequisite: This nerdctl release is expected to be used with containerd v1.7 or later; some features may not work with other containerd releases." ### nerdctl images supports --tree (2026-09-20) - slug: nerdctl-images-supports-tree-1ade038fbbea - score: 0.94 How to use it: When reviewing platforms declared by local images, run `nerdctl images --tree` to list each image with a row per declared platform. Examples: ``` nerdctl images --tree ``` - why_it_matters: Review the platforms declared by local images. - sources: , - gotchas: "Version: v2.4.0"; "--tree: Lists multi-platform images as a tree; documented as experimental. Cannot be combined with `--quiet`, `--no-trunc`, `--digests`, `--format`, or `--names`." ### nerdctl network create supports --aux-address (2026-09-20) - slug: nerdctl-network-create-supports-aux-address-16fb279dcbdd - score: 0.94 How to use it: When creating a network with reserved auxiliary addresses, run `nerdctl network create` with one or more `--aux-address name=IP` pairs. Each IP is reserved and never assigned to a container; each pair is matched to the subnet containing its IP. Examples: ``` nerdctl network create --subnet= --aux-address== ``` - why_it_matters: Create a network with auxiliary address configuration. - sources: , - gotchas: "Version: v2.4.0"; "NETWORK (required): Name of the network to create; the command syntax requires this argument."; "--aux-address: Repeatable `name=IP` pair for an auxiliary IPv4 or IPv6 address. Each IP is reserved from container assignment and matched to the subnet containing it."; "--subnet: Subnet in CIDR format representing a network segment." ### nerdctl network create supports IPv6-only networks (2026-09-20) - slug: nerdctl-network-create-supports-ipv6-only-networks-458ac1cce92e - score: 0.98 How to use it: When creating an IPv6-only network, disable IPv4 and enable IPv6; provide a valid IPv6 subnet. Examples: ``` nerdctl network create --ipv4=false --ipv6 --subnet

``` - why_it_matters: Create an IPv6-only network. - before: Before this change, nerdctl had no `--ipv4` equivalent to disable IPv4 for an IPv6-only network. - sources: , - gotchas: "Version: v2.4.0"; "--ipv4=false: Disable IPv4; supported with `--ipv6` and an IPv6 subnet. Not supported on Windows."; "--ipv6: Enable IPv6; use with a valid subnet."; "--subnet : Set the network segment in CIDR format; an IPv6 subnet is needed for IPv6-only creation."; " (required): Name of the network to create."; "Prerequisite: Use a valid IPv6 subnet. CNI plugins v1.1.0 or later are needed to isolate the CNI bridge."; "Prerequisite: nerdctl v2.4.0 is expected to be used with containerd v1.7 or later." ### nerdctl network filters OR repeated name values (2026-09-20) - slug: nerdctl-network-filters-or-repeated-name-values-318b8ed9c2ea - score: 0.92 How to use it: When you need to list networks matching more than one name, run `nerdctl network ls` with repeated `--filter name=` values; nerdctl v2.4.0 combines them with OR. Examples: ``` nerdctl network ls --filter name= --filter name= ``` - why_it_matters: Filter networks by more than one name. - sources: - gotchas: "Version: v2.4.0"; "--filter name=: Filter networks by name; repeat the filter to match values with OR. The v2.4.0 command reference does not document this flag’s name filter syntax." ### nerdctl push supports --all-tags (2026-09-20) - slug: nerdctl-push-supports-all-tags-0e7ff3417eaf - score: 0.99 How to use it: When pushing every local tag for a repository, run `nerdctl push --all-tags `; the repository name must not include a tag. Examples: ``` nerdctl push --all-tags ``` - why_it_matters: Push every local tag for a repository to a registry. - sources: , - gotchas: "Version: v2.4.0"; "--all-tags: Push all tags of an image to the repository. Alias: `-a`."; "NAME (required): Image/repository name; with `--all-tags`, it must not contain a tag." ### nerdctl rootless networking enables IPv6 in the RootlessKit namespace (2026-09-20) - slug: nerdctl-rootless-networking-enables-ipv6-in-the-rootlesskit-namespace-6dd86a57c26c - score: 0.97 How to use it: When testing IPv6 for a rootless container, set `CONTAINERD_ROOTLESS_ROOTLESSKIT_IPV6=true` and restart rootless containerd, then create an IPv6-capable CNI network with `nerdctl network create --ipv6 --subnet `. IPv6 mainly affects outgoing connections with `slirp4netns` and `pasta`; `gvisor-tap-vsock` does not support IPv6, and the built-in port driver does not forward IPv6 ports. Examples: ``` Environment=CONTAINERD_ROOTLESS_ROOTLESSKIT_IPV6="true" ``` ``` systemctl --user daemon-reload && systemctl --user restart containerd ``` ``` nerdctl network create --ipv6 --subnet ``` - why_it_matters: Test a rootless container's IPv6 networking in a development environment. - before: Use the rootless network namespace without IPv6 enabled. - sources: , , , - gotchas: "Version: v2.4.0"; "CONTAINERD_ROOTLESS_ROOTLESSKIT_IPV6: Boolean setting for IPv6 inside the RootlessKit network namespace; defaults to false. Set to true to enable."; "--ipv6: Enables IPv6 on the network; use with a valid subnet."; "--subnet : Specifies a subnet in CIDR format; use a valid IPv6 subnet for this task."; " (required): Network name positional argument for `nerdctl network create`."; "Prerequisite: Rootless containerd must be set up; the docs direct users to `containerd-rootless-setuptool.sh install`."; "Prerequisite: CNI plugins v1.1.0 or later are required to isolate the CNI bridge."; "The setting defaults to false."; "The setting mainly affects outgoing connections with `slirp4netns` and `pasta` network drivers."; "It does not affect port forwarding in the built-in port driver."; "The `gvisor-tap-vsock` network driver does not currently support IPv6."; "The change covers `--port-driver=builtin` (the default); `--port-driver=slirp4netns` does not yet support IPv6 port forwarding upstream." ### nerdctl save supports --quiet (2026-09-20) - slug: nerdctl-save-supports-quiet-01ba5ff030d2 - score: 0.95 How to use it: When saving images without progress output, run `nerdctl save --quiet ` (or use `-q`). Examples: ``` nerdctl save --quiet ``` - why_it_matters: Save an image without progress output in a script or other quiet workflow. - sources: , - gotchas: "Version: v2.4.0"; "IMAGE (required): One or more images to save."; "--quiet (-q): Suppresses progress output." ### nerdctl supports Docker v25 recursive read-only bind mounts (2026-09-20) - slug: nerdctl-supports-docker-v25-recursive-read-only-bind-mounts-44b30cb5659a - score: 0.95 How to use it: When a bind mount must make its submounts recursively read-only, use `--mount` with `readonly,bind-recursive=readonly`; this forces recursive read-only and errors if unsupported. For automatic behavior, use `bind-recursive=enabled` (the default), which makes read-only mounts recursive when supported. Examples: ``` nerdctl run --mount type=bind,source=,target=,readonly,bind-recursive=readonly ``` ``` nerdctl run --mount type=bind,source=,target=,readonly,bind-propagation=rprivate,bind-recursive=readonly ``` - why_it_matters: Configure a bind mount to make its submounts recursively read-only where the kernel and OCI runtime support it. - before: Use the older `rro` option, which is now deprecated in favor of the Docker v25 `bind-recursive` form. - sources: , , - gotchas: "Version: v2.4.0"; "--mount (required): Attaches a filesystem mount using comma-separated key-value pairs."; "type=bind (required): Selects a bind mount."; "source / src (required): Host mount source; mandatory for bind mounts."; "target / dst / destination (required): Mount destination in the container."; "readonly / ro: Mounts the filesystem read-only; recursively read-only when kernel and runtime support it."; "bind-recursive: Bind-specific setting: `enabled` (default) recursively binds submounts and makes read-only mounts recursively read-only when supported; `disabled` omits submounts; `writable` keeps submounts writable on a read-only mount; `readonly` forces recursive read-only and errors if unsupported. Values are mutually exclusive; `readonly` requires `bind-propagation=rprivate`."; "bind-propagation: Bind propagation setting; allowed values are `shared`, `slave`, `private`, `rshared`, `rslave`, `rprivate` (default `rprivate`). Specify `rprivate` with `bind-recursive=readonly`."; "Prerequisite: Recursive read-only support requires Linux kernel >= 5.12 and runc >= 1.1 or crun >= 1.8.6. `bind-recursive=readonly` errors when the kernel or runtime lacks support."; "Prerequisite: Runtime support is detected with `$RUNTIME features`; the result is cached in the XDG cache directory."; "Recursive read-only behavior depends on kernel >= 5.12 and runc >= 1.1 or crun >= 1.8.6."; "The `rro` option is deprecated; the source says it raises an error when recursive read-only mounts are unsupported."; "Runtime feature detection uses `$RUNTIME features`, with results cached in the XDG cache directory and invalidated when the runtime binary is modified." ### nerdctl system df reports disk usage (2026-09-20) - slug: nerdctl-system-df-reports-disk-usage-3a2515558463 - score: 0.96 How to use it: When inspecting nerdctl-managed disk usage, run `nerdctl system df` for the current namespace. Add `--verbose` (`-v`) for detailed space usage or `--format ` to format the output. Examples: ``` nerdctl system df ``` ``` nerdctl system df --verbose ``` ``` nerdctl system df --format 'table {{.Type}}\t{{.Size}}' ``` - why_it_matters: Inspect disk usage for nerdctl-managed resources while maintaining a development environment. - sources: , - gotchas: "Version: v2.4.0"; "--verbose, -v: Show detailed information on space usage."; "--format : Format output with a Go template; `table` prints default columns, while `table TEMPLATE` prints template columns with a header and alignment."; "Prerequisite: nerdctl v2.4.0 is expected to be used with containerd v1.7 or later; some features may not work with other containerd releases." ### nerdctl compose down accepts service names (2026-05-21) - slug: nerdctl-compose-down-accepts-service-names-dedcd01a11ba - score: 0.90 How to use it: When stopping selected services in a Compose project, pass their names to `nerdctl compose down` to remove their containers and associated resources. Examples: ``` nerdctl compose down [ ...] ``` - why_it_matters: Stop selected services from a Compose project during repository development. - sources: , - gotchas: "Version: v2.3.1"; "SERVICE names (required): Service names to pass to `compose down`; the v2.3.1 release note says service names are supported, but does not document whether this argument is optional or how many names are accepted."; "Prerequisite: `nerdctl compose` requires nerdctl >= 0.8."; "Docs conflict: The v2.3.1 command reference lists `nerdctl compose down [OPTIONS]` without service arguments, while the v2.3.1 release note says service names are supported." ### nerdctl compose supports service healthcheck (2026-05-21) - slug: nerdctl-compose-supports-service-healthcheck-99b28357a33a - score: 0.94 How to use it: When maintaining a repository’s container setup, add a `healthcheck` mapping to the Compose service to define how its containers are checked for health. nerdctl v2.3.1 documents `healthcheck.start_interval` as unimplemented. Examples: ``` services: : healthcheck: test: ["CMD", "curl", "-f", "http://localhost"] interval: 1m30s timeout: 10s retries: 3 start_period: 40s ``` - why_it_matters: Configure a Compose service health check when maintaining a repository's container setup. - sources: , , - gotchas: "Version: v2.3.1"; "healthcheck.test: Command used to check health; a string or list. A list begins with `NONE`, `CMD`, or `CMD-SHELL`; a string is equivalent to `CMD-SHELL` followed by that string."; "healthcheck.interval: Duration between checks."; "healthcheck.timeout: Duration before a check is considered failed."; "healthcheck.retries: Number of consecutive failures needed to report the container unhealthy."; "healthcheck.start_period: Duration to wait during container initialization before counting failures toward the retry threshold."; "healthcheck.start_interval: Duration between checks during the start period. nerdctl v2.3.1 lists this field as unimplemented."; "Prerequisite: nerdctl >= 0.8 is required for `nerdctl compose`." ### nerdctl build supports --source-policy-file (2026-05-05) - slug: nerdctl-build-supports-source-policy-file-17fc54ea7088 - score: 0.96 How to use it: When building a repository image with a BuildKit source policy, run `nerdctl build --source-policy-file

`. The policy file is JSON; the documented no-op example is `{"rules":[]}`. Examples: ``` nerdctl build --source-policy-file

``` - why_it_matters: Build a repository image with a source policy file. - sources: , - gotchas: "Version: v2.3.0"; "--source-policy-file : BuildKit source policy JSON file for reproducible builds."; "PATH (required): Build context path; the command usage requires `PATH`."; "Prerequisite: `buildkitd` must be running for `nerdctl build`." ### nerdctl cp supports tarballs (2026-05-05) - slug: nerdctl-cp-supports-tarballs-4232cf2a8c99 - score: 0.95 How to use it: When copying a tar archive from the host into a container, stream it to `nerdctl cp` with `-` as the source and a container directory as the destination. The container must be running. Examples: ``` tar -cf - | nerdctl cp - : ``` - why_it_matters: Copy files using tarballs with nerdctl. - sources: , - gotchas: "Version: v2.3.0"; "nerdctl cp [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH (required): Copy from the local filesystem or stdin into a container. Use `-` for the tar archive on stdin; the destination must be a directory."; "CONTAINER (required): Target container; the command is documented for a running container."; "-L, --follow-link: Always follow symbolic links in SRC_PATH."; "Prerequisite: nerdctl v2.3.0 or later for the release-added tarball support."; "Prerequisite: The target container must be running. Use only with trusted, cooperating containers." ### nerdctl search command support (2026-05-05) - slug: nerdctl-search-command-support-06f103b17ce7 - score: 0.95 How to use it: When searching a repository workflow for container images, run `nerdctl search `; it searches Docker Hub or a registry for images. Examples: ``` nerdctl search ``` - why_it_matters: Search for container images from a repository workflow. - sources: , - gotchas: "Version: v2.3.0"; "TERM (required): Search term for images."; "--limit: Maximum number of search results; default 0."; "--no-trunc: Do not truncate output; default false."; "--filter, -f: Filter output based on provided conditions; documented conditions not specified."; "--format: Format output using a Go template."