Installing Image Builder

  • Red Hat Enterprise Linux 8
  • Updated 04 November 2020
  • Published 27 October 2021

Installing Image Builder

Red Hat Enterprise Linux 8
  • Updated 16 October 2020
  • Published 04 November 2020

Image Builder is a tool for creating custom system images. Before using Image Builder, you must install Image Builder in a virtual machine.

Image Builder system requirements

The osbuild-composer tool underlying Image Builder performs a number of potentially insecure and unsafe actions while creating the system images. For this reason, use a virtual machine to run Image Builder.

The environment where Image Builder runs, for example the virtual machine, must meet requirements listed in the following table.

Table 1. Image Builder system requirements
Parameter Minimal Required Value

System type

A dedicated virtual machine


2 cores


4 GiB

Disk space

20 GiB

Access privileges

Administrator level (root)


Connectivity to Internet

There is no support for creating images on virtual machine directly installed on UEFI systems.

Installing Image Builder in a virtual machine

To install Image Builder on a dedicated virtual machine, follow these steps:

  • Connect to the virtual machine.

  • The virtual machine for Image Builder must be installed, subscribed, and running.

  1. Install the Image Builder and other necessary packages on the virtual machine:

    • osbuild-composer

    • composer-cli

    • cockpit-composer

    • bash-completion

    # yum 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 cockpit.socket

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

  3. Configure the system firewall to allow access to the web console:

    # firewall-cmd --add-service=cockpit && firewall-cmd --add-service=cockpit --permanent
  4. 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 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 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.

Reverting to lorax-composer Image Builder backend

The osbuild-composer backend, though much more extensible, does not currently achieve feature parity with the previous lorax-composer backend.

To revert to the previous backend, follow the steps:

  • You have installed the osbuild-composer package

  1. Remove the osbuild-composer backend.

    # yum remove osbuild-composer
  2. In the /etc/yum.conf file, add an exclude entry for osbuild-composer package.

    # cat /etc/yum.conf
  3. Install the "lorax-composer" package.

    # yum install lorax-composer
Additional resources