Chapter 2. Installing image builder

Before using image builder, you must install image builder in a virtual machine.

2.1. Installing image builder in a virtual machine

To install image builder on a dedicated virtual machine (VM), follow these steps:


  • You must be connected to a RHEL VM.
  • The VM for image builder must be running and subscribed to Red Hat Subscription Manager (RHSM) or Red Hat Satellite.
  • You have enabled the BaseOS and AppStream repositories to be able to install the RHEL image builder packages.


  1. Install the image builder and other necessary packages on the VM:

    • osbuild-composer - supported from RHEL 8.3 onward
    • composer-cli
    • cockpit-composer
    • bash-completion
    # dnf install osbuild-composer composer-cli cockpit-composer bash-completion

    The web console is installed as a dependency of the cockpit-composer package.

  2. Enable image builder to start after each reboot:

    # systemctl enable --now osbuild-composer.socket
    # systemctl enable --now cockpit.socket

    The osbuild-composer and cockpit services start automatically on first access.

  3. Load the shell configuration script so that the autocomplete feature for the composer-cli command starts working immediately without reboot:

    $ source /etc/bash_completion.d/composer-cli

The osbuild-composer package is the new backend engine that will be the preferred default and focus of all new functionality beginning with Red Hat Enterprise Linux 8.3 and later. The previous backend lorax-composer package is considered deprecated, will only receive select fixes for the remainder of the Red Hat Enterprise Linux 8 life cycle and will be omitted from future major releases. It is recommended to uninstall lorax-composer in favor of osbuild-composer.


You can use a system journal to track RHEL image builder activities. Additionally, you can find the log messages in the file.

  • To find the journal output for traceback, run the following commands:

    $ journalctl | grep osbuild
  • To show both remote or local workers:

    $ journalctl -u osbuild-worker*
  • To show the running services:

    $ journalctl -u osbuild-composer.service