clipper pull

Pull a chunked image and load it into the local container runtime.

clipper [--runtime=<runtime>] pull <src> [<name>] [flags]

Arguments

Argument	Description
`<src>`	Image reference (e.g. `myuser/ubuntu:latest`)
`[<name>]`	Local image name. Defaults to the source reference.

Flags

Flag	Default	Description
`-j, --jobs`	`4`	Parallel chunk fetch workers
`--fetch-only`	`false`	Fetch chunks to local store only, skip loading into the runtime
`--direct`	`false`	Apply layers directly to snapshots, skipping the content store (faster, but the result can’t be pushed). Requires containerd. Cannot be combined with `--fetch-only`.
`--reflink`	`false`	Reflink (copy-on-write clone) chunks into snapshots instead of copying. Requires `--direct` and an xfs or btrfs filesystem.
`--platform`	auto-detect	Target platform (e.g. `linux/amd64`)
`--namespace`	`moby`	Containerd namespace to pull to

Global flags

--runtime is a global flag and must come before the subcommand, e.g. clipper --runtime=containerd <command> .... It forces the container runtime: containerd, podman, or docker (default: auto-detect). See Container Runtimes.

Examples

Pull an image

clipper pull myuser/ubuntu:latest

Pull with a custom local name

clipper pull myuser/ubuntu:latest my-ubuntu:latest

Pull with more parallelism

clipper pull myuser/large-image:latest -j 16

Fetch chunks without loading

clipper pull --fetch-only myuser/ubuntu:latest

This downloads all chunks to the local store (~/.local/share/clipper/) without importing into Docker/containerd. Useful for pre-caching.

Direct apply (fastest)

sudo clipper --runtime=containerd pull --direct --reflink myuser/ubuntu:latest

Applies chunks straight to containerd snapshots, skipping the content store. Add --reflink on xfs or btrfs to clone chunks copy-on-write instead of copying. The pulled image runs locally but can’t be re-pushed.

How it works

Fetches the manifest from the registry
Downloads chunks for each layer, skipping any already in the local store
Reconstructs the original tar layers from chunks
Loads the image into the local container runtime (Docker, containerd, or Podman)

For containerd, clipper applies layers directly to snapshots without going through a tar intermediary, which is faster.