---
next_cursor: eyJzY29yZSI6MCwic2VxIjoxMTkyLCJzaW5jZSI6bnVsbCwidG9vbCI6Im5lcmRjdGwiLCJ2IjoxfQ
has_more: true
next: https://sincecutoff.com/v1/changes.md?tool=nerdctl&score=0&cursor=eyJzY29yZSI6MCwic2VxIjoxMTkyLCJzaW5jZSI6bnVsbCwidG9vbCI6Im5lcmRjdGwiLCJ2IjoxfQ
items: 10
---
# sincecutoff.com changes: nerdctl

## nerdctl build supports --source-policy-file (nerdctl, 2026-05-05)
Published 2026-10-16
- 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 <policy.json> <repository-path>`. The policy file is JSON; the documented no-op example is `{"rules":[]}`.

Examples:

```
nerdctl build --source-policy-file <policy.json> <repository-path>
```

- why_it_matters: Build a repository image with a source policy file.
- sources: <https://github.com/containerd/nerdctl/releases/tag/v2.3.0>, <https://github.com/containerd/nerdctl/blob/v2.3.0/docs/command-reference.md>
- gotchas: "Version: v2.3.0"; "--source-policy-file <policy.json>: 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 (nerdctl, 2026-05-05)
Published 2026-10-16
- 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 - <host-path> | nerdctl cp - <container>:<destination-directory>
```

- why_it_matters: Copy files using tarballs with nerdctl.
- sources: <https://github.com/containerd/nerdctl/releases/tag/v2.3.0>, <https://github.com/containerd/nerdctl/blob/v2.3.0/docs/command-reference.md>
- 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 (nerdctl, 2026-05-05)
Published 2026-10-16
- slug: nerdctl-search-command-support-06f103b17ce7
- score: 0.95

How to use it:

When searching a repository workflow for container images, run `nerdctl search <TERM>`; it searches Docker Hub or a registry for images.

Examples:

```
nerdctl search <TERM>
```

- why_it_matters: Search for container images from a repository workflow.
- sources: <https://github.com/containerd/nerdctl/releases/tag/v2.3.0>, <https://github.com/containerd/nerdctl/blob/v2.3.0/docs/command-reference.md>
- 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."

## nerdctl compose down accepts service names (nerdctl, 2026-05-21)
Published 2026-10-16
- 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 <service> [<service> ...]
```

- why_it_matters: Stop selected services from a Compose project during repository development.
- sources: <https://github.com/containerd/nerdctl/releases/tag/v2.3.1>, <https://github.com/containerd/nerdctl/blob/v2.3.1/docs/compose.md>
- 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 (nerdctl, 2026-05-21)
Published 2026-10-16
- 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:
  <service>:
    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: <https://github.com/containerd/nerdctl/releases/tag/v2.3.1>, <https://github.com/compose-spec/compose-spec/blob/main/spec.md>, <https://github.com/containerd/nerdctl/blob/v2.3.1/docs/compose.md>
- 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 compose supports image volumes (nerdctl, 2026-09-20)
Published 2026-10-16
- 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:
  <SERVICE>:
    volumes:
      - type: image
        source: <IMAGE_REFERENCE>
        target: <CONTAINER_PATH>

# From the Compose project directory:
nerdctl compose up
```

- why_it_matters: Maintain a Compose project that mounts an image volume.
- sources: <https://github.com/containerd/nerdctl/releases/tag/v2.4.0>, <https://github.com/containerd/nerdctl/blob/v2.4.0/docs/compose.md>
- gotchas: "Version: v2.4.0"; "services.<SERVICE>.volumes[].type (required): Set to `image` for an image volume."; "services.<SERVICE>.volumes[].source (required): Image reference used as the mount source."; "services.<SERVICE>.volumes[].target (required): Container path where the image is mounted; the v2.4.0 Compose image-volume docs do not describe this field."; "services.<SERVICE>.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 (nerdctl, 2026-09-20)
Published 2026-10-16
- 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=<image>,target=<container-path>`. To mount a relative path within the image rootfs, add `image-subpath=<relative-path>`; the image filesystem is read-only.

Examples:

```
nerdctl run --rm --mount type=image,src=<image>,target=<container-path> <container-image>
```

```
nerdctl run --rm --mount type=image,src=<image>,target=<container-path>,image-subpath=<relative-path> <container-image>
```

- why_it_matters: Run a container with read-only access to an image or a path inside its root filesystem.
- sources: <https://github.com/containerd/nerdctl/releases/tag/v2.4.0>, <https://github.com/containerd/nerdctl/blob/v2.4.0/docs/command-reference.md>
- 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."; "<container-image> (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 (nerdctl, 2026-09-20)
Published 2026-10-16
- 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: <https://github.com/containerd/nerdctl/releases/tag/v2.4.0>
- 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 (nerdctl, 2026-09-20)
Published 2026-10-16
- 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: <https://github.com/containerd/nerdctl/releases/tag/v2.4.0>, <https://github.com/containerd/nerdctl/pull/4999>, <https://github.com/containerd/nerdctl/blob/v2.4.0/pkg/cmd/system/events.go>
- gotchas: "Version: v2.4.0"; "--filter (-f): Filter events by a condition; for this task, use `label=<key>=<value>`."; "label=<key>=<value> (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 (nerdctl, 2026-09-20)
Published 2026-10-16
- 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: <https://github.com/containerd/nerdctl/releases/tag/v2.4.0>, <https://github.com/containerd/nerdctl/blob/v2.4.0/docs/command-reference.md>
- 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`."

Next: https://sincecutoff.com/v1/changes.md?tool=nerdctl&score=0&cursor=eyJzY29yZSI6MCwic2VxIjoxMTkyLCJzaW5jZSI6bnVsbCwidG9vbCI6Im5lcmRjdGwiLCJ2IjoxfQ
Save `next_cursor`; next visit, pass it to get only what was published since.
<!-- end of page -->