{"id":13424812,"url":"https://github.com/containerd/nerdctl","last_synced_at":"2025-09-09T21:25:54.075Z","repository":{"id":37033861,"uuid":"318476701","full_name":"containerd/nerdctl","owner":"containerd","description":"contaiNERD CTL - Docker-compatible CLI for containerd, with support for Compose, Rootless, eStargz, OCIcrypt, IPFS, ...","archived":false,"fork":false,"pushed_at":"2024-07-24T06:07:10.000Z","size":8395,"stargazers_count":7697,"open_issues_count":297,"forks_count":573,"subscribers_count":48,"default_branch":"main","last_synced_at":"2024-07-24T09:56:08.520Z","etag":null,"topics":["containerd"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/containerd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-04T10:09:03.000Z","updated_at":"2024-08-17T21:40:13.177Z","dependencies_parsed_at":"2024-03-11T02:33:25.089Z","dependency_job_id":"e6dd6366-6505-4ed3-9c78-964757dcf952","html_url":"https://github.com/containerd/nerdctl","commit_stats":{"total_commits":1456,"total_committers":126,"mean_commits":"11.555555555555555","dds":0.5927197802197802,"last_synced_commit":"5a3858c9ce9a17d6d54890eabd5054aded2f496a"},"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/containerd%2Fnerdctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/containerd%2Fnerdctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/containerd%2Fnerdctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/containerd%2Fnerdctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/containerd","download_url":"https://codeload.github.com/containerd/nerdctl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243775932,"owners_count":20346290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containerd"],"created_at":"2024-07-31T00:00:59.718Z","updated_at":"2025-09-09T21:25:54.057Z","avatar_url":"https://github.com/containerd.png","language":"Go","readme":"[[⬇️ **Download]**](https://github.com/containerd/nerdctl/releases)\n[[📖 **Command reference]**](./docs/command-reference.md)\n[[❓**FAQs \u0026 Troubleshooting]**](./docs/faq.md)\n[[📚 **Additional documents]**](#additional-documents)\n\n# nerdctl: Docker-compatible CLI for containerd\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/images/nerdctl.svg\"\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/images/nerdctl-white.svg\"\u003e\n  \u003cimg alt=\"logo\" src=\"docs/images/nerdctl.svg\"\u003e\n\u003c/picture\u003e\n\n`nerdctl` is a Docker-compatible CLI for [contai**nerd**](https://containerd.io).\n\n ✅ Same UI/UX as `docker`\n\n ✅ Supports Docker Compose (`nerdctl compose up`)\n\n ✅ [Optional] Supports [rootless mode, without slirp overhead (bypass4netns)](./docs/rootless.md)\n\n ✅ [Optional] Supports lazy-pulling ([Stargz](./docs/stargz.md), [Nydus](./docs/nydus.md), [OverlayBD](./docs/overlaybd.md))\n\n ✅ [Optional] Supports [encrypted images (ocicrypt)](./docs/ocicrypt.md)\n\n ✅ [Optional] Supports [P2P image distribution (IPFS)](./docs/ipfs.md) (\\*1)\n\n ✅ [Optional] Supports [container image signing and verifying (cosign)](./docs/cosign.md)\n\nnerdctl is a **non-core** sub-project of containerd.\n\n\\*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](https://docs.ipfs.io/install/).\n\n## Examples\n\n### Basic usage\n\nTo run a container with the default `bridge` CNI network (10.4.0.0/24):\n\n```console\n# nerdctl run -it --rm alpine\n```\n\nTo build an image using BuildKit:\n\n```console\n# nerdctl build -t foo /some-dockerfile-directory\n# nerdctl run -it --rm foo\n```\n\nTo build and send output to a local directory using BuildKit:\n\n```console\n# nerdctl build -o type=local,dest=. /some-dockerfile-directory\n```\n\nTo run containers from `docker-compose.yaml`:\n\n```console\n# nerdctl compose -f ./examples/compose-wordpress/docker-compose.yaml up\n```\n\nSee also [`./examples/compose-wordpress`](./examples/compose-wordpress).\n\n### Debugging Kubernetes\n\nTo list local Kubernetes containers:\n\n```console\n# nerdctl --namespace k8s.io ps -a\n```\n\nTo build an image for local Kubernetes without using registry:\n\n```console\n# nerdctl --namespace k8s.io build -t foo /some-dockerfile-directory\n# kubectl apply -f - \u003c\u003cEOF\napiVersion: v1\nkind: Pod\nmetadata:\n  name: foo\nspec:\n  containers:\n    - name: foo\n      image: foo\n      imagePullPolicy: Never\nEOF\n```\n\nTo load an image archive (`docker save` format or OCI format) into local Kubernetes:\n\n```console\n# nerdctl --namespace k8s.io load \u003c /path/to/image.tar\n```\n\nTo read logs (experimental):\n```console\n# nerdctl --namespace=k8s.io ps -a\nCONTAINER ID    IMAGE                                                      COMMAND                   CREATED          STATUS    PORTS    NAMES\n...\ne8793b8cca8b    registry.k8s.io/coredns/coredns:v1.9.3                     \"/coredns -conf /etc…\"    2 minutes ago    Up                 k8s://kube-system/coredns-787d4945fb-mfx6b/coredns\n...\n\n# nerdctl --namespace=k8s.io logs -f e8793b8cca8b\n[INFO] plugin/reload: Running configuration SHA512 = 591cf328cccc12bc490481273e738df59329c62c0b729d94e8b61db9961c2fa5f046dd37f1cf888b953814040d180f52594972691cd6ff41be96639138a43908\nCoreDNS-1.9.3\nlinux/amd64, go1.18.2, 45b0a11\n...\n```\n\n### Rootless mode\n\nTo launch rootless containerd:\n\n```console\n$ containerd-rootless-setuptool.sh install\n```\n\nTo run a container with rootless containerd:\n\n```console\n$ nerdctl run -d -p 8080:80 --name nginx nginx:alpine\n```\n\nSee [`./docs/rootless.md`](./docs/rootless.md).\n\n## Install\n\nBinaries are available here: \u003chttps://github.com/containerd/nerdctl/releases\u003e\n\nIn addition to containerd, the following components should be installed:\n\n- [CNI plugins](https://github.com/containernetworking/plugins): for using `nerdctl run`.\n  - v1.1.0 or later is highly recommended.\n- [BuildKit](https://github.com/moby/buildkit) (OPTIONAL): for using `nerdctl build`. BuildKit daemon (`buildkitd`) needs to be running. See also [the document about setting up BuildKit](./docs/build.md).\n  - v0.11.0 or later is highly recommended. Some features, such as pruning caches with `nerdctl system prune`, do not work with older versions.\n- [RootlessKit](https://github.com/rootless-containers/rootlesskit) and [slirp4netns](https://github.com/rootless-containers/slirp4netns) (OPTIONAL): for [Rootless mode](./docs/rootless.md)\n  - RootlessKit needs to be v0.10.0 or later. v2.0.0 or later is recommended.\n  - slirp4netns needs to be v0.4.0 or later. v1.1.7 or later is recommended.\n\nThese dependencies are included in `nerdctl-full-\u003cVERSION\u003e-\u003cOS\u003e-\u003cARCH\u003e.tar.gz`, but not included in `nerdctl-\u003cVERSION\u003e-\u003cOS\u003e-\u003cARCH\u003e.tar.gz`.\n\n### Brew\n\nOn Linux systems you can install nerdctl via [brew](https://brew.sh):\n\n```bash\nbrew install nerdctl\n```\n\nThis is currently not supported for macOS. The section below shows how to install on macOS using brew.\n\n### macOS\n\n[Lima](https://github.com/lima-vm/lima) project provides Linux virtual machines for macOS, with built-in integration for nerdctl.\n\n```console\n$ brew install lima\n$ limactl start\n$ lima nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine\n```\n\n### FreeBSD\n\nSee [`./docs/freebsd.md`](docs/freebsd.md).\n\n### Windows\n\n- Linux containers: Known to work on WSL2\n- Windows containers: experimental support for Windows (see below for features that are currently known to work)\n\n### Docker\n\nTo run containerd and nerdctl inside Docker:\n\n```bash\ndocker build -t nerdctl .\ndocker run -it --rm --privileged nerdctl\n```\n\n## Motivation\n\nThe goal of `nerdctl` is to facilitate experimenting the cutting-edge features of containerd that are not present in Docker (see below).\n\nNote that competing with Docker is _not_ the goal of `nerdctl`. Those cutting-edge features are expected to be eventually available in Docker as well.\n\nAlso, `nerdctl` might be potentially useful for debugging Kubernetes clusters, but it is not the primary goal.\n\n## Features present in `nerdctl` but not present in Docker\n\nMajor:\n\n- On-demand image pulling (lazy-pulling) using [Stargz](./docs/stargz.md)/[Nydus](./docs/nydus.md)/[OverlayBD](./docs/overlaybd.md)/[SOCI](./docs/soci.md) Snapshotter: `nerdctl --snapshotter=stargz|nydus|overlaybd|soci run IMAGE` .\n- [Image encryption and decryption using ocicrypt (imgcrypt)](./docs/ocicrypt.md): `nerdctl image (encrypt|decrypt) SRC DST`\n- [P2P image distribution using IPFS](./docs/ipfs.md): `nerdctl run ipfs://CID` .\n  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](https://docs.ipfs.io/install/).\n- [Cosign integration](./docs/cosign.md): `nerdctl pull --verify=cosign` and `nerdctl push --sign=cosign`, and [in Compose](./docs/cosign.md#cosign-in-compose)\n- [Accelerated rootless containers using bypass4netns](./docs/rootless.md): `nerdctl run --annotation nerdctl/bypass4netns=true`\n\nMinor:\n\n- Namespacing: `nerdctl --namespace=\u003cNS\u003e ps` .\n  (NOTE: All Kubernetes containers are in the `k8s.io` containerd namespace regardless to Kubernetes namespaces)\n- Exporting Docker/OCI dual-format archives: `nerdctl save` .\n- Importing OCI archives as well as Docker archives: `nerdctl load` .\n- Specifying a non-image rootfs: `nerdctl run -it --rootfs \u003cROOTFS\u003e /bin/sh` . The CLI syntax conforms to Podman convention.\n- Connecting a container to multiple networks at once: `nerdctl run --net foo --net bar`\n- Running [FreeBSD jails](./docs/freebsd.md).\n- Better multi-platform support, e.g., `nerdctl pull --all-platforms IMAGE`\n- Applying an (existing) AppArmor profile to rootless containers: `nerdctl run --security-opt apparmor=\u003cPROFILE\u003e`.\n  Use `sudo nerdctl apparmor load` to load the `nerdctl-default` profile.\n- Systemd compatibility support: `nerdctl run --systemd=always`\n\nTrivial:\n\n- Inspecting raw OCI config: `nerdctl container inspect --mode=native` .\n\n## Features implemented in `nerdctl` ahead of Docker\n\n- Recursive read-only (RRO) bind-mount: `nerdctl run -v /mnt:/mnt:rro` (make children such as `/mnt/usb` to be read-only, too).\n  Requires kernel \u003e= 5.12.\nThe same feature was later introduced in Docker v25 with a different syntax. nerdctl will support Docker v25 syntax too in the future.\n## Similar tools\n\n- [`ctr`](https://github.com/containerd/containerd/tree/main/cmd/ctr): incompatible with Docker CLI, and not friendly to users.\n  Notably, `ctr` lacks the equivalents of the following nerdctl commands:\n  - `nerdctl run -p \u003cPORT\u003e`\n  - `nerdctl run --restart=always --net=bridge`\n  - `nerdctl pull` with `~/.docker/config.json` and credential helper binaries such as `docker-credential-ecr-login`\n  - `nerdctl logs`\n  - `nerdctl build`\n  - `nerdctl compose up`\n\n- [`crictl`](https://github.com/kubernetes-sigs/cri-tools): incompatible with Docker CLI, not friendly to users, and does not support non-CRI features\n- [k3c v0.2 (abandoned)](https://github.com/rancher/k3c/tree/v0.2.1): needs an extra daemon, and does not support non-CRI features\n- [Rancher Kim (nee k3c v0.3)](https://github.com/rancher/kim): needs Kubernetes, and only focuses on image management commands such as `kim build` and `kim push`\n- [PouchContainer (abandoned?)](https://github.com/alibaba/pouch): needs an extra daemon\n\n## Developer guide\n\nnerdctl is a containerd **non-core** sub-project, licensed under the [Apache 2.0 license](./LICENSE).\nAs a containerd non-core sub-project, you will find the:\n\n- [Project governance](https://github.com/containerd/project/blob/main/GOVERNANCE.md),\n- [Maintainers](./MAINTAINERS),\n- and [Contributing guidelines](https://github.com/containerd/project/blob/main/CONTRIBUTING.md)\n\ninformation in our [`containerd/project`](https://github.com/containerd/project) repository.\n\n### Compiling nerdctl from source\n\nRun `make \u0026\u0026 sudo make install`.\n\nSee the header of [`go.mod`](./go.mod) for the minimum supported version of Go.\n\nUsing `go install github.com/containerd/nerdctl/v2/cmd/nerdctl` is possible, but unrecommended because it does not fill version strings printed in `nerdctl version`\n\n### Testing\n\nSee [testing nerdctl](docs/testing/README.md).\n\n### Contributing to nerdctl\n\nLots of commands and flags are currently missing. Pull requests are highly welcome.\n\nPlease certify your [Developer Certificate of Origin (DCO)](https://developercertificate.org/), by signing off your commit with `git commit -s` and with your real name.\n\n# Command reference\n\nMoved to [`./docs/command-reference.md`](./docs/command-reference.md)\n\n# Additional documents\n\nConfiguration guide:\n\n- [`./docs/config.md`](./docs/config.md): Configuration (`/etc/nerdctl/nerdctl.toml`, `~/.config/nerdctl/nerdctl.toml`)\n- [`./docs/registry.md`](./docs/registry.md): Registry authentication (`~/.docker/config.json`)\n\nBasic features:\n\n- [`./docs/compose.md`](./docs/compose.md):   Compose\n- [`./docs/rootless.md`](./docs/rootless.md): Rootless mode\n- [`./docs/cni.md`](./docs/cni.md): CNI for containers network\n- [`./docs/build.md`](./docs/build.md): `nerdctl build` with BuildKit\n\nAdvanced features:\n\n- [`./docs/stargz.md`](./docs/stargz.md):     Lazy-pulling using Stargz Snapshotter\n- [`./docs/nydus.md`](./docs/nydus.md):       Lazy-pulling using Nydus Snapshotter\n- [`./docs/overlaybd.md`](./docs/overlaybd.md):       Lazy-pulling using OverlayBD Snapshotter\n- [`./docs/ocicrypt.md`](./docs/ocicrypt.md): Running encrypted images\n- [`./docs/gpu.md`](./docs/gpu.md):           Using GPUs inside containers\n- [`./docs/multi-platform.md`](./docs/multi-platform.md):  Multi-platform mode\n\nExperimental features:\n\n- [`./docs/experimental.md`](./docs/experimental.md):  Experimental features\n- [`./docs/freebsd.md`](./docs/freebsd.md):  Running FreeBSD jails\n- [`./docs/ipfs.md`](./docs/ipfs.md): Distributing images on IPFS\n- [`./docs/builder-debug.md`](./docs/builder-debug.md): Interactive debugging of Dockerfile\n\nImplementation details:\n\n- [`./docs/dir.md`](./docs/dir.md):           Directory layout (`/var/lib/nerdctl`)\n\nMisc:\n\n- [`./docs/faq.md`](./docs/faq.md): FAQs and Troubleshooting\n","funding_links":[],"categories":["Go","others","HarmonyOS"],"sub_categories":["Windows Manager"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontainerd%2Fnerdctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontainerd%2Fnerdctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontainerd%2Fnerdctl/lists"}