Skip to main content
Version: 6

Qt Debian Container for Torizon


Toradex provides Qt containers with the base Qt5 libraries installed. It makes it easy for you to extend this container with your application and its dependencies. See some advantages of using this container:

  • You can keep applications independent
  • Use different runtimes
  • Encapsulate application dependencies in the container
  • It will be easier to maintain

The following containers from Toradex are available:

  • qt5-wayland: minimal container with Qt5 libraries. You should use it as the base for deploying your own app.
  • qt5-wayland-examples: built on top of qt5-wayland with qtbase5-examples and qtdeclarative5-examples. You can use it for a great out-of-the-box evaluation experience, as described in this article.

This article complies with the Typographic Conventions for Torizon Documentation.


The following prerequisites are proposed:

Executing the Containers​

Run a Weston Container​

Connect to the board terminal by establishing an SSH connection.

Start a Weston container which will be the graphics server. Choose your module from the tabs below and follow the instructions:

(Optional) pull the torizon/weston container image:

# docker pull torizon/weston:$CT_TAG_WESTON

Start the weston compositor:

# docker run -d --rm --name=weston --net=host --cap-add CAP_SYS_TTY_CONFIG \
-v /dev:/dev -v /tmp:/tmp -v /run/udev/:/run/udev/ \
--device-cgroup-rule='c 4:* rmw' --device-cgroup-rule='c 13:* rmw' \
--device-cgroup-rule='c 226:* rmw' \
torizon/weston:$CT_TAG_WESTON --developer --tty=/dev/tty7

To learn more about the device_cgroup_rules section of the docker-compose file above, please refer to the Hardware Access through Control Group Rules (cgroup) section of the Torizon Best Practices Guide

Run a Qt Wayland Container​

Start a Qt Wayland examples container. It works on top of Wayland, as explained in Debian Containers for Torizon, and has Qt libraries. When you package your own application, use the base instead of the examples image to save flash storage space.

Select your module from the tabs below and follow the instructions:

The following command brings up the Qt5 Wayland container with an interactive command prompt:

# docker run --rm -it --name=qt5 \
-v /tmp:/tmp \
-v /dev/dri:/dev/dri --device-cgroup-rule='c 226:* rmw' \
torizon/qt5-wayland-examples:$CT_TAG_QT5_WAYLAND_EXAMPLES \

Use the Qt Quick 2D Renderer​

Inside the Qt5 Wayland container, only if you are using a module without GPU (Colibri iMX7 and Colibri iMX6ULL) and plan to also use Qt Quick, we recommend that you use the Qt Quick 2D Renderer, otherwise you may see a poor performance and high CPU load:


only export QMLSCENE_DEVICE=softwarecontext if your module does not have a GPU!

## export QMLSCENE_DEVICE=softwarecontext

Keep in mind that there are feature limitations when using the Qt Quick 2D Renderer.

Start a Qt Sample Application (32-bit SoCs)​

Inside the Qt5 Wayland container, start any of the available Qt5 sample applications:

## /usr/lib/arm-linux-gnueabihf/qt5/examples/quick/animation/animation &


## /usr/lib/arm-linux-gnueabihf/qt5/examples/widgets/widgets/calculator/calculator &


## /usr/lib/arm-linux-gnueabihf/qt5/examples/widgets/widgets/shapedclock/shapedclock &


## /usr/lib/arm-linux-gnueabihf/qt5/examples/opengl/cube/cube &

Executing the QT5 Containers through Portainer​

The image TorizonCore with evaluation containers has many different demos. For instructions about how to install Torizon on your board, refer to Toradex Quickstart Guide. In this image, the Weston container starts automatically after boot, therefore you do not need to start it.

With Portainer opened, explore the demos by going to the App Templates section in Portainer and click on the QT template and then click on Deploy The Container.

Available Container Examples in Portainer

This demo will execute the 3D Cube example. After creating and executing the container, you can edit the container to execute other demos. To do that, click on the Containers menu and select the qt5-app container

Containers menu

On the container's menu, click on the Duplicate/Edit button

Click on the Duplicate/Edit button

Edit the CMD field with the other demos' paths, as shown in the previous section, and click on the Deploy the Container button.

CMD Field

The demo will start as a new overlay in Weston.

More Information​

Also, please watch the video session below for more information.

Send Feedback!