# How to Convert Existing Container Images to Nydus Format Using Nydusify

> Easily convert existing container images to Nydus format with nydusify. Optimize for lazy loading and chunk deduplication. Learn how to use this powerful CLI tool for your container images.

- Repository: [dragonflyoss/nydus](https://github.com/dragonflyoss/nydus)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Nydusify is a high-level CLI tool that orchestrates the conversion of standard OCI container images into Nydus format by driving the nydus-image builder layer-by-layer, optionally pushing blobs to remote storage backends, and generating a new image manifest that enables lazy loading and chunk deduplication.**

Converting existing container images to Nydus format using nydusify allows you to leverage the dragonflyoss/nydus repository's high-performance image distribution capabilities without rebuilding images from scratch. The tool handles the entire transformation pipeline—from parsing source manifests to assembling RAFS (Registry Accelerated File System) bootstraps—making it the standard method for migrating workloads to the Nydus ecosystem.

## Understanding the Nydusify Conversion Architecture

The conversion process relies on three primary components working in sequence. First, the CLI entry point in [`contrib/nydusify/cmd/nydusify.go`](https://github.com/dragonflyoss/nydus/blob/main/contrib/nydusify/cmd/nydusify.go) parses flags such as `--source`, `--target`, and backend configurations, then validates archives via `validateSourceAndTargetArchives` and resolves target references through `getTargetReference`.

Second, the `converter` package ([`contrib/nydusify/pkg/converter/convert.go`](https://github.com/dragonflyoss/nydus/blob/main/contrib/nydusify/pkg/converter/convert.go)) implements the core `converter.Convert` function. This component iterates over each platform layer of the source image, invokes the `nydus-image` binary to create RAFS bootstraps and data blobs, and manages concurrent layer processing.

Third, backend helpers in [`contrib/nydusify/pkg/utils/backend.go`](https://github.com/dragonflyoss/nydus/blob/main/contrib/nydusify/pkg/utils/backend.go) (specifically `utils.NewRegistryBackendConfig`) generate JSON configurations for blob storage, supporting registry-native storage, OSS, S3, and local filesystem backends.

## Basic Conversion Workflow

### Simple Registry-to-Registry Conversion

The most common use case pulls an OCI image from a registry, converts it to Nydus format, and pushes the result back to the same or a different registry:

```bash
nydusify convert \
  --source <registry>/<repo>:<tag> \
  --target <registry>/<repo>:<tag>-nydus

```

This command processes every layer in the source image, generates corresponding Nydus bootstrap and blob files, and creates a new manifest referencing these artifacts. The resulting image tag `<tag>-nydus` can be consumed by containerd with the Nydus snapshotter.

### Using Target Suffixes

Instead of specifying a full target reference, you can use `--target-suffix` to automatically append a string to the source tag:

```bash
nydusify convert \
  --source myregistry/app:1.2.3 \
  --target-suffix -nydus

```

Internally, `nydusify` calls `getTargetReference` to concatenate the source reference with the suffix, producing `myregistry/app:1.2.3-nydus`. This reduces CLI verbosity when batch-converting images with consistent naming conventions.

## Advanced Conversion Scenarios

### Converting from Local OCI Archives

For air-gapped environments or pre-downloaded images, convert directly from a local OCI archive file:

```bash
nydusify convert \
  --source myregistry/app:1.2.3 \
  --source-archive /tmp/app-oci.tar \
  --target myregistry/app:1.2.3-nydus

```

The `validateSourceAndTargetArchives` function in [`cmd/nydusify.go`](https://github.com/dragonflyoss/nydus/blob/main/cmd/nydusify.go) verifies the archive path exists before conversion begins. This workflow is essential for CI/CD pipelines that cache images as tarballs.

### Exporting to Local OCI Archives

Conversely, you can convert and export the result to a local archive without pushing to a registry:

```bash
nydusify convert \
  --source myregistry/app:1.2.3 \
  --target myregistry/app:1.2.3-nydus \
  --target-archive /tmp/app-nydus.tar

```

The resulting tarball contains the Nydus image manifest, bootstrap, and blob layers, suitable for manual inspection or distribution via alternative channels.

### Configuring External Object Storage Backends (OSS/S3)

For production deployments, store large data blobs in object storage while keeping the lightweight bootstrap in the registry. First, create a backend configuration JSON file.

For Alibaba Cloud OSS ([`oss-config.json`](https://github.com/dragonflyoss/nydus/blob/main/oss-config.json)):

```json
{
  "endpoint": "region.aliyuncs.com",
  "scheme": "https",
  "access_key_id": "<your-id>",
  "access_key_secret": "<your-secret>",
  "bucket_name": "nydus-bucket",
  "object_prefix": "nydus/"
}

```

Then run:

```bash
nydusify convert \
  --source myregistry/app:1.2.3 \
  --target myregistry/app:1.2.3-nydus \
  --backend-type oss \
  --backend-config-file ./oss-config.json

```

The `utils.NewRegistryBackendConfig` helper in [`pkg/utils/backend.go`](https://github.com/dragonflyoss/nydus/blob/main/pkg/utils/backend.go) constructs the appropriate backend configuration when `--backend-type` is omitted (defaulting to registry storage). For S3-compatible storage, use `--backend-type s3` with a similar JSON structure containing `endpoint`, `access_key_id`, `secret_access_key`, `bucket_name`, and `region`.

### Enabling Build Cache for Incremental Builds

Accelerate repeated conversions by caching layer artifacts:

```bash
nydusify convert \
  --source myregistry/app:1.2.3 \
  --target myregistry/app:1.2.3-nydus \
  --build-cache myregistry/cache:latest \
  --build-cache-tag v1

```

The `converter.Opt` struct in [`cmd/nydusify.go`](https://github.com/dragonflyoss/nydus/blob/main/cmd/nydusify.go) passes cache parameters to `converter.Convert`, which checks for existing layer blobs before re-converting unchanged content. This is particularly effective in CI environments where base images change infrequently.

### Chunk Deduplication with Chunk-Dict

Reduce storage footprint across multiple images by referencing a shared chunk dictionary:

```bash
nydusify convert \
  --source myregistry/app:1.2.3 \
  --target myregistry/app:1.2.3-nydus \
  --chunk-dict bootstrap=/path/to/dict.boot

```

The chunk dictionary (`dict.boot`) contains pre-computed chunk hashes. During conversion, `nydusify` identifies duplicate chunks between the source image and the dictionary, referencing existing blobs instead of creating new ones. This is documented in the chunk-deduplication documentation and handled within the converter package.

### Prefetch Optimization Patterns

Improve container startup latency by pre-fetching critical files:

```bash
cat prefetch.txt | nydusify convert \
  --source myregistry/app:1.2.3 \
  --target myregistry/app:1.2.3-nydus \
  --prefetch-patterns

```

The [`prefetch.txt`](https://github.com/dragonflyoss/nydus/blob/main/prefetch.txt) file contains absolute paths (one per line) that the Nydus runtime should fetch immediately upon image mount. The converter passes these patterns to `nydus-image`, which embeds them in the RAFS metadata for runtime optimization.

### Reverse Conversion (Experimental)

Convert Nydus images back to standard OCI format:

```bash
nydusify convert \
  --source myregistry/app:1.2.3-nydus \
  --target myregistry/app:1.2.3-oci \
  --reverse

```

The `--reverse` flag triggers `converter.ReverseConvert` (implemented in [`contrib/nydusify/pkg/converter/reverse.go`](https://github.com/dragonflyoss/nydus/blob/main/contrib/nydusify/pkg/converter/reverse.go)), which reconstructs standard OCI layers from Nydus RAFS metadata and data blobs. Note that this feature is experimental and may not support all Nydus features.

## Key Source Files and Implementation Details

Understanding the codebase helps troubleshoot complex conversions:

| File | Purpose | Key Functions |
|------|---------|---------------|
| [`contrib/nydusify/cmd/nydusify.go`](https://github.com/dragonflyoss/nydus/blob/main/contrib/nydusify/cmd/nydusify.go) | CLI entry point and flag parsing | `getTargetReference`, `validateSourceAndTargetArchives`, `converter.Convert` invocation |
| [`contrib/nydusify/pkg/converter/convert.go`](https://github.com/dragonflyoss/nydus/blob/main/contrib/nydusify/pkg/converter/convert.go) | Core conversion logic | `Convert` (loops layers, calls `nydus-image`), manifest assembly |
| [`contrib/nydusify/pkg/converter/reverse.go`](https://github.com/dragonflyoss/nydus/blob/main/contrib/nydusify/pkg/converter/reverse.go) | Experimental reverse conversion | `ReverseConvert` |
| [`contrib/nydusify/pkg/utils/backend.go`](https://github.com/dragonflyoss/nydus/blob/main/contrib/nydusify/pkg/utils/backend.go) | Backend configuration helpers | `NewRegistryBackendConfig` |
| [`docs/nydusify.md`](https://github.com/dragonflyoss/nydus/blob/main/docs/nydusify.md) | User-facing documentation | Flag reference and examples |

The conversion flow in `converter.Convert` handles platform-specific layers concurrently, invokes the `nydus-image` binary for RAFS creation, and manages blob upload to the configured backend (registry, OSS, S3, or localfs).

## Summary

- **Nydusify** is the official CLI tool for converting existing container images to Nydus format, orchestrating the `nydus-image` builder and backend storage operations.
- The conversion process supports multiple workflows: registry-to-registry, local archive import/export, and external object storage backends (OSS/S3) for blob separation.
- Performance optimizations include **build caching** (`--build-cache`), **chunk deduplication** (`--chunk-dict`), and **prefetch patterns** to reduce startup latency.
- The tool is implemented in [`contrib/nydusify/cmd/nydusify.go`](https://github.com/dragonflyoss/nydus/blob/main/contrib/nydusify/cmd/nydusify.go) with core logic in `pkg/converter`, supporting experimental reverse conversion back to OCI format.

## Frequently Asked Questions

### What is the difference between nydusify and nydus-image?

**Nydusify** is a high-level CLI tool that orchestrates the entire conversion workflow, including pulling source images, managing layers, and pushing results to registries. **Nydus-image** is the low-level binary that performs the actual RAFS (Registry Accelerated File System) bootstrap and data blob creation for individual layers. Nydusify invokes nydus-image internally during the conversion process.

### Can I convert images without pushing to a registry?

Yes, you can use the `--target-archive` flag to export the converted Nydus image to a local OCI archive file instead of pushing to a registry. For example: `nydusify convert --source myregistry/app:1.2.3 --target myregistry/app:1.2.3-nydus --target-archive /tmp/app-nydus.tar`. This is useful for offline distribution or local testing.

### How does the build cache improve conversion performance?

The build cache (`--build-cache` flag) stores previously converted layer artifacts in a specified registry repository. When converting images that share layers with previous builds (such as updated versions of the same base image), nydusify checks the cache repository for existing blobs before re-converting unchanged layers. This significantly reduces conversion time and computational overhead in CI/CD pipelines.

### Is reverse conversion from Nydus to OCI fully supported?

Reverse conversion is currently experimental and available via the `--reverse` flag. It triggers the `converter.ReverseConvert` function in [`contrib/nydusify/pkg/converter/reverse.go`](https://github.com/dragonflyoss/nydus/blob/main/contrib/nydusify/pkg/converter/reverse.go), which reconstructs standard OCI layers from Nydus RAFS metadata. However, this feature may not support all Nydus-specific optimizations (such as certain chunking strategies or compression formats), so it should be used with caution in production environments.