ch-grow - Man Page

Build an image from a Dockerfile; completely unprivileged





This script is experimental. Please report the bugs you find so we can fix them!

Build an image named TAG as specified in DOCKERFILE; use ch-run(1) to execute RUN instructions. This builder is completely unprivileged, with no setuid/setgid/setcap helpers.

ch-grow maintains state and temporary images using normal files and directories. This storage directory can reside on any filesystem, and its location is configurable. In descending order of priority:

-s, --storage DIR

Command line option.


Environment variable.




Images are stored unpacked, so place your storage directory on a filesystem that can handle the metadata traffic for large numbers of small files. For example, the Charliecloud test suite uses approximately 400,000 files and directories.

Other arguments:


Context directory; this is the root of COPY and ADD instructions in the Dockerfile.

--build-arg KEY[=VALUE]

Set build-time variable KEY defined by ARG instruction to VALUE. If VALUE not specified, use the value of environment variable KEY.


Report any dependency problems and exit. If all is well, there is no output and the exit code is zero; in case of problems, the exit code is non-zero.

-f, --file DOCKERFILE

Use DOCKERFILE instead of CONTEXT/Dockerfile.

-h, --help

Print help and exit.

-n, --dry-run

Do not actually execute any Dockerfile instructions.


Ignored (ch-grow does not yet support layer caching).


Stop after parsing the Dockerfile.


Print the storage directory path and exit. Must be after --storage, if any, for correct results.

-t, -tag TAG

Name of image to create. Append :latest if no colon present.

-v, --verbose

Print extra chatter; can be repeated.


Print version number and exit.


This script executes RUN instructions with host EUID and EGID both mapped to zero in the container, i.e., with ch-run --uid=0 gid=0. This confuses many programs that appear in RUN, which see EUID 0 and/or EGID 0 and assume they can actually do privileged things, which then fail with “permission denied” and related errors. For example, chgrp(1) often appears in Debian package post-install scripts. We have worked around some of these problems, but many remain; please report any you find as bugs.

COPY and ADD source paths are not restricted to the context directory. However, because ch-grow is completely unprivileged, this cannot be used to add files not normally readable by the user to the image.

Reporting Bugs

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

Otherwise, report bugs to: <>

See Also


Full documentation at: <>

Referenced By

charliecloud(1), ch-tug(1).

2020-04-16 00:00 Coordinated Universal Time 0.15 Charliecloud