Your company here — click to reach over 10,000 unique daily visitors

osbuild - Man Page

Build-Pipelines for Operating System Artifacts


osbuild [ OPTIONS ] -
osbuild --help
osbuild --version


osbuild is a build-system for operating system artifacts. It takes an input manifest describing the build pipelines and produces file-system trees, images, or other artifacts as output. Its pipeline description gives comprehensive control over the individual steps to execute as part of a pipeline. osbuild provides isolation from the host system as well as caching capabilities, and thus ensures that pipeline builds will be deterministic and efficient.


osbuild reads the pipeline description from the file passed on the command-line. To make osbuild read the pipeline description from standard input, pass -.

The following command-line options are supported. If an option is passed, which is not listed here, osbuild will deny startup and exit with an error.

-h,  --help

print usage information and exit immediately


print version information and exit immediately


directory where intermediary file system trees are stored

-l DIR--libdir=DIR

directory containing stages, assemblers, and the osbuild library


maximum size of the cache (bytes) or 'unlimited' for no restriction (size may include an optional unit suffix, like kB, kiB, MB, MiB and so on)


stage to commit to the object store during build (can be passed multiple times)


object to export (can be passed multiple times)


output results in JSON format


directory where result objects are stored


return the manifest in JSON format including all the ids


name of the monitor to be used


file-descriptor to be used for the monitor


set the maximal time (in seconds) each stage is allowed to run


open debug shell when executing stages; accepts stage name or id (from --inspect) or * (for all)

NB: If neither --output-directory nor --checkpoint is specified, no attempt to build the manifest will be made.


The input to osbuild is a description of the pipelines to execute, as well as required parameters to each pipeline stage. This data must be JSON encoded. It is read from the file specified on the command-line, or, if - is passed, from standard input.

The format of the manifest is described in osbuild-manifest(5). The formal schema of the manifest is available online as the OSBuild JSON Schema [1].


Live activity of the pipeline execution can be monitored via a built-in set of different monitors. The --monitor=TYPE option selects the type of monitor that is used. Valid types are:


No live coverage is reported and all monitoring features are disabled. This is the default monitor if --json was specified on the command-line.


A human-readable live monitor of the pipeline execution. This monitor prints pipeline names, stage names, and relevant options of each stage as it is executed. Additionally, timing information is provided for each stage. The output is not machine-readable and is interspersed with the individual log messages of the stages. This is the default monitor if --json was not specified.


A json-sequence (RFC7464) based live monitor of the pipeline execution. Each line contains valid json and a record-separator (0x1E) at the end. The json consists of a progress object that contains a context object describes the context of the progress and details about the progress. Progress can be nested and a progress object may contain sub-progress. In addition each progress can emit message strings that contain detailed log information from the stage. An example:

"message": "Starting module org.osbuild.grub2.inst",
"context": {
"origin": "osbuild.monitor",
"pipeline": {
"name": "image",
"id": "b3e63a8ef3cd30be244ffe1749af05783014bf2c61b2e45f09bb6df0ef122ad8",
"stage": {
"name": "org.osbuild.grub2.inst",
"id": "b3e63a8ef3cd30be244ffe1749af05783014bf2c61b2e45f09bb6df0ef122ad8"
"id": "747c04fa9265e7de79ac5efae43c62375f4b6bb778cb24abd7963dc181139176"
"progress": {
"name": "pipelines/sources",
"total": 4,
"done": 3,
"progress": {
"name": "stages",
"total": 7,
"done": 6
"timestamp": 1710318022.3872378

Monitor output is written to the file-descriptor provided via --monitor-fd=NUM. If none was specified, standard output is used.


OSBuild only ever builds the requested artifacts, rather than all artifacts defined in a manifest. Each stage and pipeline has an associated ID (which can be acquired by passing --inspect). To export an artifact after a stage or pipeline finished, pass its ID via --export=ID. A sub-directory will be created in the output-directory with the ID as the name. The contents of the artifact are then stored in that sub-directory.

Additionally, any completed pipeline or stage can be cached to avoid rebuilding them in subsequent invocations. Use --checkpoint=ID to request caching of a specific stage or pipeline.


The following sub-sections contain examples on running osbuild. Generally, osbuild must be run with superuser privileges, since this is required to create file-system images.

Example 1: Run an empty pipeline

To verify your osbuild setup, you can run it on an empty pipeline which produces no output:

# echo {} | osbuild -

Example 2: See pipeline IDs of a Fedora qcow2 image

To inspect a basic qcow2 image of Fedora, use:

# osbuild ./samples/fedora-boot.json

The pipeline definition ./samples/fedora-boot.json is provided in the upstream source repository of osbuild.

This will print out the pipeline IDs of the provided manifest but will not actually build anything because no artifact was requested. The pipeline IDs can then be passed to --export= to actually get the requested artifacts.

Example 3: Build a Fedora qcow2 image

To build a basic qcow2 image of Fedora, use:

# osbuild --output-dir ./out --export image ./samples/fedora-boot.json

Note that the command requires to be run as root. It will create an out/image directory and put the generated "disk.img" there.

Example 4: Run from a local checkout

To run osbuild from a local checkout, use:

# python3 -m osbuild --libdir . --output-dir ./out --export image samples/fedora-boot.json

This will make sure to execute the osbuild module from the current directory, as well as use it to search for stages, assemblers, and more.

See Also

osbuild-manifest(5), osbuild-composer(1)



OSBuild JSON Schema v2: https://osbuild.org/schemas/osbuild2.json

Referenced By

osbuild-composer(7), osbuild-manifest(5).