Skip to main content
Version: 1.7

Working with Images

Rancher Desktop provides the ability to build, push, and pull images via the NERDCTL project and the Docker CLI.

Note, both nerdctl and docker are put into the path automatically. This occurs during the installer on Windows, and upon first run on macOS and Linux.

General Usage​

Using either tool requires Rancher Desktop to be running with the appropriate container runtime. For nerdctl, use the containerd runtime. For docker, use the Moby runtime.

You can learn about all of the command options and display the help documentation by running:

nerdctl -h

Unlike Docker, containerd features its own namespaces. By default, nerdctl images are stored in the default namespace. If you want your images available for use by Kubernetes, use the --namespace k8s.io or -n k8s.io CLI argument. You can also switch to a namespace called default or any other name using the option --namespace <NAMESPACE_NAME>. Note that nerdctl namespaces are separate and independent from Kubernetes and kubectl namespaces.

Listing Images​

To see the images currently available, run the following command:

nerdctl images

Building Images​

Building images has a similar feel to existing tools. For example, consider running nerdctl from a directory with a Dockerfile where the Dockerfile is using a scratch image.

nerdctl build .
[+] Building 0.1s (4/4) FINISHED
 => [internal] load build definition from Dockerfile
 => => transferring dockerfile: 31B
 => [internal] load .dockerignore
 => => transferring context: 2B
 => [internal] load build context
 => => transferring context: 33B
 => CACHED [1/1] ADD anvil-app /

nerdctl has options for tagging at the same time as building and other options you've come to expect.

nerdctl build -t TAG .

To build an image for use with Kubernetes, specify the k8s.io namespace as follows:

nerdctl build -n k8s.io .

Building Local Images​

In order to demonstrate the steps to build local images and run apps, a sample nodejs app is provided within the Rancher Desktop docs repository. To get started, clone the repository and cd into assets/express-sample in a terminal.

Run the following command to build image from Dockerfile:

nerdctl --namespace k8s.io build -t expressapp:v1.0 .

Run the following command to run container:

kubectl run --image expressapp:v1.0 expressapp
kubectl port-forward pods/expressapp 3000:3000

Note: When adding the latest tag, be sure to also specify the following:

imagePullPolicy: Never

Tagging Images​

If you want to tag an existing image you've built you can use the following command:

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

Removing Images​

To remove an image, run the following command:

nerdctl rmi IMAGE