---
name: "ch-convert"
section: "1"
platform: "linux"
package: "charliecloud-builders"
version: "0.38-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/ch-convert"
---

# ch-convert(1)

Convert an image from one format to another

## NAME

ch-convert - Convert an image from one format to another

## SYNOPSIS

```
$ ch-convert [-i FMT] [-o FMT] [OPTION ...] IN OUT
```

## DESCRIPTION

Copy image **IN** to **OUT** and convert its format. Replace **OUT** if it already exists, unless **--no-clobber** is specified. It is an error if **IN** and **OUT** have the same format; use the format’s own tools for that case.

**ch-run** can run container images that are plain directories or (optionally) SquashFS archives. However, images can take on a variety of other formats as well. The main purpose of this tool is to make images in those other formats available to **ch-run**.

For best performance, **ch-convert** should be invoked only once, producing the final format actually needed.

- **IN**

  Descriptor for the input image. For image builders, this is an image reference; otherwise, it’s a filesystem path.

- **OUT**

  Descriptor for the output image.

- **-h, --help**

  Print help and exit.

- **-i, --in-fmt FMT**

  Input image format is **FMT**. If omitted, inferred as described below.

- **-n, --dry-run**

  Don’t read the input or write the output. Useful for testing format inference.

- **--no-clobber**

  Error if **OUT** already exists, rather than replacing it.

- **--no-xattrs**

  Ignore xattrs and ACLs when converting. Overrides **$CH\_XATTRS**.

- **-o, --out-fmt FMT**

  Output image format is **FMT**; inferred if omitted.

- **-q, --quiet**

  Be quieter; can be repeated. Incompatible with **-v**. See the *FAQ* *entry on verbosity* for details.

- **-s, --storage DIR**

  Set the storage directory. Equivalent to the same option for **[ch-image(1)](/ch-image/1.md)** and **[ch-run(1)](/ch-run/1.md)**.

- **--tmp DIR**

  A sub-directory for temporary storage is created in **DIR** and removed at the end of a successful conversion. **If this script crashes or** **errors out, the temporary directory is left behind to assist in** **debugging.** Storage may be needed up to twice the uncompressed size of the image, depending on the input and output formats. Default: **$TMPDIR** if specified; otherwise **/var/tmp**.

- **-v, --verbose**

  Print extra chatter. Can be repeated.

- **--xattrs**

  Preserve xattrs and ACLs when converting.

## IMAGE FORMATS

**ch-convert** knows about these values of **FMT**:

- **ch-image**

  Internal storage for Charliecloud’s unprivileged image builder (Dockerfile interpreter) **ch-image**.

- **dir**

  Ordinary filesystem directory (i.e., not a mount point) containing an unpacked image. Output directories that already exist are replaced if they look like an image. If the output directory is empty, the conversion should use the directory without overwriting it. If the directory doesn’t look like an image and isn’t empty, exit with an error.

- **docker**

  Internal storage for Docker.

- **podman**

  Internal storage for Podman.

- **squash**

  SquashFS filesystem archive containing the flattened image. SquashFS archives are much like tar archives but are mountable, including by **ch-run**’s internal SquashFUSE mounting. Most systems have at least the SquashFS-Tools installed which allows unpacking into a directory, just like tar. Due to this greater flexibility, SquashFS is preferred to tar.

  **Note:** Conversions to and from SquashFS are quite noisy due to the verbosity of the underlying **[mksquashfs(1)](/mksquashfs/1.md)** and **[unsquashfs(1)](/unsquashfs/1.md)** tools.

- **tar**

  Tar archive containing the flattened image with no layer sub-archives; i.e., the output of **docker export** works but the output of **docker save** does not. Output tarballs are always gzipped and must end in **.tar.gz**; input tarballs can be any compression acceptable to **[tar(1)](/tar/1.md)**.

All of these are local formats; **ch-convert** does not know how to push or pull images.

## FORMAT INFERENCE

**ch-convert** tries to save typing by guessing formats when they are reasonably clear. This is done against filenames, rather than file contents, so the rules are the same for output descriptors that do not yet exist.

Format inference is done for both **IN** and **OUT**. The first matching glob below yields the inferred format. Paths need not exist in the filesystem.

- 1\.

  **\*.sqfs**, **\*.squash**, **\*.squashfs**: SquashFS.

- 2\.

  **\*.tar**, **\*.t?z**, **\*.tar.?**, **\*.tar.??**: Tarball.

- 3\.

  **/\***, **./\***, i.e. absolute path or relative path with explicit dot: Directory.

- 4\.

  If *ch-image* is installed: **ch-image** internal storage.

- 5\.

  If Podman is installed: Podman internal storage.

- 6\.

  If Docker is installed: Docker internal storage.

- 7\.

  Otherwise: No format inference.

## EXAMPLES

Typical build-to-run sequence for image **foo/bar** using **ch-run**’s internal SquashFUSE code, inferring the output format:

```
$ sudo docker build -t foo/bar -f Dockerfile .
[...]
$ ch-convert foo/bar:latest /var/tmp/foobar.sqfs
input:   docker    foo/bar:latest
output:  squashfs  /var/tmp/foobar.sqfs
copying ...
done
$ ch-run /var/tmp/foobar.sqfs -- echo hello
hello
```

Same conversion, but no format inference:

```
$ ch-convert -i ch-image -o squash foo/bar:latest /var/tmp/foobar.sqfs
input:   docker    foo/bar:latest
output:  squashfs  /var/tmp/foobar.sqfs
copying ...
done
```

## REPORTING BUGS

If Charliecloud was obtained from your Linux distribution, use your distribution’s bug reporting procedures.

Otherwise, report bugs to: *https://github.com/hpc/charliecloud/issues*

## SEE ALSO

[charliecloud(7)](/charliecloud/7.md)

Full documentation at: \<*https://hpc.github.io/charliecloud*\>

## COPYRIGHT

2014–2023, Triad National Security, LLC and others