Skip to main content
Version: Torizon OS 6.x.y

TorizonCore Builder Tool - Customizing Torizon OS Images


TorizonCore Builder is a tool that allows you to easily generate a custom image of Torizon OS with device configuration changes, a custom device tree and overlays, pre-provisioned containers, external kernel modules, and a splash screen. In the end, you will have a custom Torizon OS image that you can flash onto the SoM using the Toradex Easy Installer, deploy to the SoM through SSH, or push to Torizon Cloud for deploying it remotely. The tool is designed to be used on production programming and on development as well.

TorizonCore Builder Workflow

*OS Customization Files are device tree and overlays source codes, external kernel modules source files, a splash screen image, and a directory with the configuration changes captured from the device. They can be also called version-controlled artifacts.

Easily Customizing Torizon OS Images With TorizonCore Builder Tool​


Browse for TorizonCore Builder resources from the tabs below.

This article complies with the Typographic Conventions for Torizon Documentation.


  • A Toradex SoM with Torizon installed

Typical Use Cases​

TorizonCore builder tool provides multiple commands to be used in different situations. We will describe below typical TorizonCore Builder use cases and on which section the customization related to these use cases is.

Some use cases are not covered by TorizonCore Builder. Check the section Use cases not covered by TorizonCore Builder.

Customizing a Torizon OS Image for Production​

TorizonCore Builder provides standalone commands that allow you to easily customize a Torizon OS image. Such changes could be:


If you want to add a kernel module that is available in the kernel source, or in-tree, please make a request in our community. If you tell us the exact kernel config that must be enabled and it does not have a negative impact on Torizon OS, we'll add it as a module.

Deploying Torizon OS Images​

Users can deploy the image in three different ways:

To learn how to do it, refer to the Deploying the image section of this page.

Use cases not covered by TorizonCore Builder​

Due to project requirements, it is possible that customizations on the kernel source code and/or on builtin in-tree kernel modules are needed.

These customizations are not covered by TorizonCore Builder at the moment. Therefore, to perform such customizations, using Yocto Project to build your image with these kind of custom changes is the recommended approach.

Please note that on Yocto Project, it is possible to modify every detail of the final image. Therefore you might need to test and validate these implementations so that the custom build of your Torizon OS image will seamless integrate with the other elements of Torizon Ecosystem.

Keep in mind that it is possible to use the customized Torizon OS with TorizonCore Builder, Torizon Cloud, containers and the VS Code IDE Extension.

Here is a list of some customizations that should be done leveraging Yocto Project resources:

  • Bootloader (U-Boot)
  • InitRAM Filesystem (initramfs)
  • Kernel source code modifications
  • Add In-tree Kernel modules

Installing TorizonCore Builder​

OS Compatibility​

TorizonCore Builder executes in a Docker Runtime and it was tested on the following Operating Systems:

  • A Linux distribution with:
  • Windows 10 or newer with Windows Subsystem for Linux (WSL2).
    • The same Linux distribution requisites from above also apply to the Linux distribution chosen to be used in WSL2.

WSL2 requires Windows 10, updated to version 2004 (also known as the Windows 10 May 2020 Update) or higher.

Shell Compatibility​

All our tests are run on Bash. TorizonCore Builder might work with other shells, but we don't ensure it.

That said, if you face a bug in a shell that is not Bash, please report it on our community website. We'll evaluate it and make our best effort to fix it, as long as the fix is compatible with Bash and the increase in maintenance is low.

Note for Users Installing TorizonCore Builder on Windows Machine​

TorizonCore Builder support on a Windows desktop requires the "Windows Subsystem for Linux 2" (WSL 2). This is due to TorizonCore Builder relying on a Linux-based filesystem.

Before proceeding with any TorizonCore Builder instructions please set up a WSL 2 distro and Docker on your development host as shown on Configure Build Environment for Torizon Containers. As a reminder, any and all TorizonCore Builder commands should be run in your WSL 2 distro.

Finally, as a quick tip, you'll occasionally need to transfer files to and from your WSL 2 distro and your Windows host. You can actually do this by using the built-in Windows file explorer utility. This and other Windows utilities can actually be invoked from within your WSL 2 Distro. For example by doing the following in your WSL 2 Distro:

$ explorer.exe .

The above command will open the Windows file explorer in your current directory. From here you'll be able to copy/paste and move files between the WSL 2 world and the normal Windows world.

Setup Script​

To install TorizonCore Builder, read our statements on OS and shell compatibility, then follow the instructions below, in order.

  1. Download the setup script into some writable directory in your system (here we use ~/tcbdir/):

    $ mkdir -p ~/tcbdir/ && cd ~/tcbdir/
    $ wget

    If you did this before then you can skip this step unless you want to update the setup script. When you source the script (next step) it will show you a warning message if it determines an update is advisable.

  2. Source the script:

    $ cd ~/tcbdir/
    $ source

    Make sure to do this from every shell instance that you intend to use with TorizonCore Builder. For advanced usage, run source -h, or see the project README. The latter has information about using the early-access version of the tool for those interested.

    • Remember to source the setup script every time you start a new terminal (or shell instance).
    • The setup script installs a Bash completion script for TorizonCore Builder, making it possible to autocomplete commands and parameters by just pressing the TAB key.

    Beware that under Windows, you must pass extra parameters to the script when the use of the following commands is intended:

  3. Verify that the command torizoncore-builder is available:

    $ torizoncore-builder --help

Using TorizonCore Builder​

This section shows how to use TorizonCore Builder in a simple way, yet covering almost all use cases. It is based on the build command, which allows the full image customization in a single step, using a configuration YAML file. The other commands that are necessary in conjunction with the build command in order to cover most use cases are also explained in this section.

If your use case is not covered here, please refer to the TorizonCore Builder - Commands Manual section for a detailed explanation of all TorizonCore Builder commands.


  • Create a configuration file with the desired settings (the build command can even help you with that);
  • Customize the configuration file in order to select the desired input image, include the desired customization, and get the desired outputs. Also, run the auxiliary commands where needed so all local artifacts possibly referenced by the configuration file are available;
  • Run the build command;
  • Deploy the output to the board or to Torizon Cloud server;

To learn about TorizonCore Builder workflow and the different approaches to use the tool, with explanatory diagrams, please refer to the TorizonCore Builder - Workflow article.

Creating a Configuration File​

The easiest and thus recommended way for creating an initial configuration file is by running:

$ torizoncore-builder build --create-template

The previous command will create a file named tcbuild.yaml containing all possible configuration parameters accepted by the command.

The configuration file is in a standard YAML format which should be recognized by most modern programming editors. Any other name can be chosen for the file, but tcbuild.yaml is the name that the build command will expect by default when running in build mode. Most parameters in the generated file will be commented out which can be seen by the # character at the beginning of each line. Lines having the characters >> are just explaining the contents of the file and should be left as-is or removed if desired.

The contents of the file are organized in a tree structure where the leaves are configurable properties. In order to set a certain property, you need to make sure all its parent properties are also uncommented (by removing the first # character).

The configuration file follows the YAML format and syntax. The tool expects it to be made up of three sections, represented by the top-level properties (keys): input, customization, and output as outlined below:

# Configuration file outline:
# Input section items (required).
# Customization section items.
# Output section items (required).

Customizing The Configuration File​

Minimal Configuration File​

A minimal configuration file has to specify at least one input and one output. Below we assume that the input is a previously downloaded Toradex Easy Installer image that is stored in a directory called images relative to the working directory (set by the alias of the tool).

When downloading a Toradex Easy Installer image, be sure to download an image without evaluation containers, because the input image to be customized MUST NOT contain bundled container images. To download the image, go to the Toradex Download Links (Torizon, Linux BSP, WinCE and Partner Demos) article.

# Sample configuration file:
local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar
local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

The directory structure of such a "project" would look like this:

├── images
│ └── torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar
└── tcbuild.yaml
Fetching Remote Images​

The input to the tool can also be specified as a URL to a remote server instead of a directory with a downloaded image, as in the Minimal Configuration section. If the input is passed as a remote image, the image will be downloaded every time the image is built.

In the sample configuration below, we directly download an image from Toradex's artifacts server:

# Sample configuration input, specifying a remote:
remote: ";sha256sum=49fc6a32ab3fc21a184fb8333c19ad53f22875975219883c1087d929bedf470f"

Notice the presence of the sha256sum parameter which can be used to ensure that the downloaded file has a certain SHA-256 checksum – the tool will stop if the actual file checksum does not match that value. For more information about how a remote location can be specified please refer to the build command Detailed Manual.

Fetching remote images: URL autogenerated​

Another way to specify an input is the sample configuration below:

# Sample configuration input, specifying parameters for URL autogeneration:
version: "5.3.0"
release: quarterly
machine: colibri-imx6
distro: torizon-upstream
variant: torizon-core-docker
build-number: "7"
#build-date: "202107"

The build command then autogenerates the URL shown in the remote parameter of the Fetching Remote Images section. For monthly and nightly releases the parameter build-date is needed.

Splash Screen​

To customize the splash screen, insert the configuration below:

#Sample customization: insert a Splash Screen
# >> Splash screen:
splash-screen: splash.png

The file splash.png should be available before running the build command. A demo image can be downloaded by clicking on the button below:

Example Splash Screen Image

Check the Splash Screen on Torizon OS article for more details.

Device Tree​

This customization can be used both with Toradex's device trees and overlays as well as any other compatible device tree and overlay. The files containing the source code of the device trees and overlays should be available before running the build command.

You just need to execute this once. In order to clone the right branch of the repository, you should first download an image and unpack it accordingly with your device.

If you have not unpacked an image yet, download a base Torizon OS image (preferably without containers) inside the TorizonCore Builder working directory, then run the command below to unpack it. In the example below the torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar image is used as a reference:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar

If you want to change the Torizon OS base image, download the new image and run the images unpack command again, passing the new image as the argument.

For more details about the images unpack command, please check the images unpack command in the commands manual.

Instead of using the images unpack you can use the images download command. This command checks which is the connected Toradex SoM, downloads the compatible latest quarterly release of a Torizon OS image without containers, and unpacks this image.

$ torizoncore-builder images download --remote-host --remote-username torizon --remote-password torizon

Change the arguments --remote-host,--remote-username and --remote-password to your board IP Address, username and password, respectively.

For more details on how the images download command works, please check the images download command in the commands manual.

To get the source code of the Toradex-supplied device tree files (including overlays), you need to clone two repositories:

  • Linux kernel: it contains the device trees and headers that both device trees and overlays might reference. For i.MX 6/6ULL/7, we use the upstream kernel directly from, and for i.MX 8/8X/8M Mini/8M Plus we provide our own fork based on the NXP downstream kernel.
  • Device tree overlays: this is a repository with overlays provided by Toradex. You need to use a specific branch and commit depending on the Torizon OS version and whether it uses the upstream kernel or our fork based on the NXP downstream.

Cloning the linux or linux-toradex repositories may take a while. You can use the --depth 1 option to clone only the latest commit. For more information, see the Git documentation.

Then, to get the source code of the Toradex supplied device tree files (including overlays), one could use the commands below:

$ git clone -b toradex_5.15-2.2.x-imx git:// linux
$ git clone -b toradex_5.15-2.2.x-imx git:// device-trees

You will end up with linux and device-trees directories.

To see the available device trees and select the appropriate one for your device, run the command below, passing the parameter -name accordingly to your device.

$ find linux -name "*imx8mp-verdin*.dts"

Then to check the available overlays names for a particular device tree (imx6dl-colibri-eval-v3.dtb in this case), run the command below:

Make sure to copy the full path of the device tree file, as device trees for different modules can be located in different paths.

$ torizoncore-builder dto list --device-tree ./linux/arch/arm/boot/dts/imx6dl-colibri-eval-v3.dts

Overlays compatible with device tree imx6dl-colibri-eval-v3.dts:
- device-trees/overlays/colibri-imx6_hdmi_overlay.dts
- device-trees/overlays/colibri-imx6_panel-cap-touch-10inch-lvds_overlay.dts
- device-trees/overlays/colibri-imx6_panel-cap-touch-7inch_adapter_overlay.dts
- device-trees/overlays/colibri-imx6_panel-cap-touch-7inch_overlay.dts
- device-trees/overlays/colibri-imx6_panel-res-touch-7inch_overlay.dts
- device-trees/overlays/colibri-imx6_spidev_overlay.dts
- device-trees/overlays/colibri-imx6_vga-640x480_overlay.dts

To generate a custom Torizon OS image using the build command, use the target device-tree file in the customization: device-tree: custom section and linux/include folder in the customization: include-dirs: section: For example, to build a custom image with the colibri-imx6_hdmi_overlay.dts overlay, the tcbuild.yaml file should be:

# Sample configuration file:
local: torizon-core-docker-colibri-imx6-Tezi_6.1.0+build.1.tar
# Sample customization: insert the hdmi overlay in the IMX6
- linux/include
custom: linux/arch/arm/boot/dts/imx6dl-colibri-eval-v3.dts
- device-trees/overlays/colibri-imx6_hdmi_overlay.dts

local: torizon-core-docker-colibri-imx6-Tezi_6.1.0+build.CUSTOM

Alternatively, you can use the dto deploy command with the --device-tree option. For example, to deploy the colibri-imx6_hdmi_overlay.dts overlay, run the command below:

$ torizoncore-builder dto deploy --remote-host --remote-username torizon --remote-password torizon --reboot --device-tree ./linux/arch/arm/boot/dts/imx6dl-colibri-eval-v3.dts device-trees/overlays/colibri-imx6_hdmi_overlay.dts

Then to include the device tree and the overlays in the image, use the customization below:

#Sample customization: insert the resistive 7" display overlay in the IMX6 device tree with Aster Carrier Board
- device-trees/include/
custom: device-trees/dts-arm32/imx6dl-colibri-eval-v3.dts
- device-trees/overlays/display-edt7_overlay.dts

See the following articles for more information:

Also, for more details on how the dt commands work, please check the dt command in the commands manual.

Kernel Modules​

The build command allows you to build and install kernel modules into the deployed OS image. This is demonstrated in this configuration:

# Sample customization: build hello-mod module into the image
- source-dir: hello-mod/
autoload: no

The directory hello-mod containing the source code files of the kernel modules should be available before running the command. To get the hello-mod module from our Github repository, run the command below:

$ git clone

For more general information about the subject, please refer to Building External Kernel Modules With Torizon article.

Kernel Arguments (Parameters)​

Kernel arguments (parameters) can be included in the OS image or modified, if they already exist, with the build command. This is done in the configuration file below:

# Sample customization: include or change (if already exists) key1 and key2 kernel arguments
- key1=val1
- key2=val2

For more general information about the subject, please refer to Customizing Kernel Arguments in Torizon article.

Capturing Configuration Changes in the Target Device​

If the user made configuration changes on Torizon OS in the SoM, this command is necessary to capture them. For more details about what it does and for which cases it is applicable, please check the Typical Use Cases section.

To capture the configuration changes made in the target device, run the command below:

$ torizoncore-builder isolate --remote-host --remote-username torizon --remote-password torizon --changes-directory changes1

Then to include these changes in the image, use the customization below:

#Sample customization: insert the configuration changes made in the device
- changes1/

See the Capturing Changes in the Configuration of a Board on Torizon OS article for detailed instructions.

Also, for more details on how the isolate command works, please check the isolate command in the commands manual.

Pre-provisioning Docker Container Images​

The build command also simplifies the process of bundling container images into an installer image. A sample configuration leveraging that feature is this:

#Sample customization: insert pre-provisioned Docker container images
local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM
compose-file: custom/docker-compose.yml

With such an input, the tool will fetch the container images referenced by the specified docker-compose.yml file and combine them with the installer image.

A sample Docker Compose YAML file can be downloaded, based on your device, by clicking in one of the links below:

Pre-provisioning Docker Container Images: Pre-bundled Container Images​

If you don't want the tool to download the images every time the build command is run, you can pass a directory with the pre-bundled container images instead of the Docker Compose file as a parameter.

To create a tarball with the container images from a Docker Compose file, in the directory bundle, use the command below:

$ torizoncore-builder bundle docker-compose.yml --bundle-directory bundle --platform linux/arm/v7

Then to include these pre-bundled container images in the image, through the directory, use the configuration below:

#Sample customization: insert pre-provisioned Docker container images with pre-built container images
local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM
dir: bundle/

Find more details in the Pre-provisioning Docker Containers onto a Torizon OS image article.

For more details on how the bundle command works, please check the bundle command in the commands manual.

Building The Custom Image of Torizon OS​

To run the tool one would simply execute:

$ torizoncore-builder build

1091 metadata, 12741 content objects imported; 412.2 MB content written
Pulling done.
Deploying OSTree with checksum 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a
Deploying done.
Copy files not under OSTree control from original deployment.
Packing rootfs...
Packing rootfs done.

=>> Build command successfully executed!

Once the build process finishes, the custom Easy Installer image would be present in the directory defined in the local of the output section of the configuration file, as it can be seen in the Minimal Configuration File section.

Different configuration file name​

The default configuration file used is the tcbuild.yaml file, created in the Creating a Configuration file section. In case of using a configuration file with a different name, run the command specifying the configuration file name:

$ torizoncore-builder build -f <configuration_file_name>
Variable substitution​

A feature that can be especially useful in CI scripts is called variable substitution which allows the replacement of property values (or parts of them) based on parameters passed on the command line of the tool. To use this feature, click on the link below and follow the steps.

Variable Substitution

The following configuration file employs that feature:

# Sample configuration input with variable substitution
local: torizon-core-docker-colibri-imx6-with-containers
name: "${IMAGE_NAME-Default image name}"
description: "${IMAGE_DESC?Please provide a description for this image}"

The value of the property output/easy-installer/name in the example is set to the value of variable IMAGE_NAME or to "Default image name" when the variable is not set. The property output/easy-installer/description depends on IMAGE_DESC which is required and if not set will cause the tool to exit showing the specified message. Running the build command by itself would fail like this:

$ torizoncore-builder build

Building image as per configuration file 'tcbuild.yaml'...

** Exiting due to user-defined error: Please provide a description for this image

In order to successfully build an image with the previous configuration file (using the default value for IMAGE_NAME), one could run:

$ torizoncore-builder build --set IMAGE_DESC="This is the required description"

For more information on the notation for replacing variables in the configuration file, please refer to the build command Detailed Manual.

Deploying The Custom Image Of Torizon OS​

The output image can be deployed in three ways to the board:

  • Using Toradex Easy Installer, the recommended method for production programming.
  • Directly on the board through SSH, the recommended method during development.
  • Through Torizon Cloud server, the recommended method to perform updates on a device already deployed to the field.

Despite the recommendations, it is also possible to use a different method, using the Torizon Cloud method during development for example.

To learn more about when to use each method, please refer to the Deployment Methods Comparison section of the TorizonCore Builder - Workflow article.

Toradex Easy Installer​

Toradex Easy Installer Tool allows users to install an image into the internal flash memory of Toradex modules in an extremely simple way.

Copy the output image into a USB stick and follow the steps in the Toradex Easy Installer article linked above. The copy of the output image can be done with the command below:

$ cp -a torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM /media/user/myUSBstick

Where, in my case, /media/user/myUSBstick is the path to USB stick mount point and torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM is the directory containing the custom Toradex Easy Installer image.

Directly, through SSH​

In this case, before deployment the output image needs to be unpacked, using the command below:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

Change the argument torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM to the directory containing your custom Toradex Easy Installer image.

For more details on how this command works, please check the images unpack command in the commands manual.

To deploy it directly to the board, through SSH, use the command below:

$ torizoncore-builder deploy --remote-host --remote-username torizon --remote-password torizon --reboot

For more details on how this command works, please check the deploy command in the commands manual.

Change the arguments --remote-host,--remote-username and --remote-password to your board IP Address, username and password, respectively.


From TorizonCore Builder 3.1.0 after, the default value of --remote-username and --remote-password is torizon, so if the username or the password is torizon the argument can be omitted.


This way does not support the deployment of the pre-provisioned containers.

Torizon Cloud​

In this case, before deployment the output image needs to be unpacked, using the command below:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

Change the argument torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM to the directory containing your custom Toradex Easy Installer image.

For more details on how this command works, please check the images unpack command in the commands manual.

To deploy it to the Torizon Cloud Update Service, use the command below:

$ torizoncore-builder platform push --credentials --package-name base-package --package-version base-package-1.0 base

For more details on how this command works, please check the platform push command documentation in the Commands Manual.


This way does not support the deployment of the pre-provisioned containers, so their Docker Compose file will need to be deployed separately in the server.

To deploy the image from the Torizon Cloud Remote Update Service to the board, please follow the steps in the OTA Web Interface article.

To obtain credentials ( file) and to obtain more information on how to sign and securely deploy a custom image using Torizon Cloud Updates, check the Signing and pushing the image to Torizon Cloud article.

Verifying The New Custom Image On The Device​

After rebooting, in your target device's terminal, verify that your new custom image of Torizon OS is active on the device with the command below:

# sudo ostree admin status

* torizon 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a.0
Version: 5.3.0+build.7-tcbuilder.20211008140217
origin refspec: tcbuilder:58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a
torizon 36ad904617b170339b6ded7b9dce87ed8cf0f76473b897fdd832d91e82eb1ddc.0 (rollback)
Version: 5.3.0+build.7
origin refspec: tcbuilder:36ad904617b170339b6ded7b9dce87ed8cf0f76473b897fdd832d91e82eb1ddc

Where 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a is the OSTree commit hash and should be the same as the one in the "Deploying OSTree with checksum ..." part of the output of the build command.

Additional Resources​

Proceed to the Documentation tab on this page.

Send Feedback!