CH-CONVERT(1)

📦
version 0.44 · 10 versions
, in ubuntu stonking

🦋 NAME 🦋

ch-convert — like, glow-up your image from one format to another, bestie 💅

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

okay so basically: copy image IN to OUT and convert its format while you're at it. If OUT is already there? It gets replaced, no hesitation — unless you passed --no-clobber, in which case it's a hard no. 🚫

And lowkey important: it is an error if IN and OUT are the same format. Like, girl, just use that format's own tools for that, fr fr.

Here's the tea: ch-run can run container images that are plain directories, or (optionally) SquashFS archives. But images come in a whole variety of other formats too, and that's the whole point — the main character energy of this tool is making images in those other formats available to ch-run. 👑

For best performance, ch-convert should be invoked only once, producing the final format you actually need. No extra passes, we keep it efficient. ✨

  • 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. 🧚

🎀 the options (DESCRIPTION, part 2) 🎀

  • -h, --help — Print help and exit. iconic behavior honestly.
  • -i, --in-fmt FMT — Input image format is FMT. If you omit it, it gets inferred, as described below. 🔍
  • -n, --dry-run — Don't read the input or write the output. Super useful for testing format inference. no cap, a great way to vibe check your globs first.
  • --no-clobber — Error if OUT already exists, rather than replacing it. protective queen 🫶
  • --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 <#faq-verbosity> for details.
  • -s, --storage DIR — Set the storage directory. Equivalent to the same option for ch-image(1) and ch-run(1).
  • --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 (it's giving crime scene, but helpful 🔎). 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. yapper mode enabled 🗣️
  • --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) and unsquashfs(1) tools. Not their fault, they're just chatty. 😭
  • 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).

All of these are local formats; ch-convert does not know how to push or pull images. sorry bestie, no registry fairy dust here 🧚

🔮 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 don't yet exist. (manifesting your file into existence, basically ✨)

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. (they handle it, not us, respectfully)

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

👀 SEE ALSO 👀

charliecloud(7)

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

contributors to the Charliecloud project, which has been established as "Charliecloud a Series of LF Projects, LLC". For web site terms of use, trademark policy, and related information, please see: https://lfprojects.org.

okay that's the whole page bestie, you ate 💅 this was version 0.44, dated 2026-05-31 07:53 UTC, and it's the CH-CONVERT(1) manual. go forth and convert, periodt 🦋✨

📦 where this page comes from