Skip to main content

Add Packages to a Yocto Image

Add a package to the image configuration when it should be available on every newly flashed board. Unlike runtime package installation, this records the package in the build configuration and produces a reproducible image.

This tutorial uses the following Python packages as an example:

  • python3-pip: installs Python packages.
  • python3-venv: creates isolated Python virtual environments.
  • python3-modules: includes a broad collection of Python standard-library modules and can noticeably increase the image size.

Before You Start​

You need a configured BSP workspace, enough disk space for an image build, the board's flashing prerequisites, and ADB access for verification.

All development-host build and artifact commands in this guide assume that the current directory is the root of the BSP workspace. The following commands use Grinn Genio BSP as an example.

Example: Grinn Genio BSP​

Development host
export KAS_CONFIG="meta-grinn-genio/kas/default.yml"
export CUSTOM_KAS_CONFIG="meta-grinn-genio/kas/custom-packages.yml"
export KAS_MACHINE=grinn-genio-700-sbc
export KAS_CONTAINER_IMAGE_DISTRO=debian-bookworm

For another platform, use the machine name and kas paths from its image build guide.

1. Create the Package Configuration​

Create the file selected by CUSTOM_KAS_CONFIG. It belongs beside the base kas configuration in the BSP metadata layer.

custom-packages.yml
header:
  version: 14

local_conf_header:
  custom-packages: |
    IMAGE_INSTALL:append = " python3-pip python3-venv python3-modules"

The important BitBake line is:

IMAGE_INSTALL:append = " python3-pip python3-venv python3-modules"

It works as follows:

  • IMAGE_INSTALL contains packages that must be installed in the generated root filesystem.
  • :append adds text without replacing the image's existing package list.
  • The leading space before python3-pip separates the first appended package from the existing value. BitBake does not add this separator automatically.

A BitBake recipe can produce several runtime packages, so a recipe name and the names accepted by IMAGE_INSTALL are not always identical. The example uses the generated package names python3-pip, python3-venv, and python3-modules.

If the base image already contains one of them, BitBake keeps the same package and does not install a duplicate.

2. Build the Image​

Pass the base configuration and extension to kas as a colon-separated list:

Development host
kas-container build "$KAS_CONFIG:$CUSTOM_KAS_CONFIG"

The extension must be stored in the same Git repository as the base kas file because kas requires composed configuration files to belong to one repository.

Wait for the build to finish and return to the shell prompt before continuing.

3. Check the Image Manifest​

Yocto writes image manifests under the selected machine's deployment directory. List the manifests from the BSP workspace root:

Development host
ls -1 "build/tmp/deploy/images/$KAS_MACHINE"/*.manifest

Choose the manifest created for the image you just built, then check for the three package names:

Development host
export IMAGE_MANIFEST="build/tmp/deploy/images/$KAS_MACHINE/<selected-manifest>"
test -f "$IMAGE_MANIFEST"
grep -E '^python3-(pip|venv|modules) ' "$IMAGE_MANIFEST"

Expected entries resemble:

Example output
python3-modules armv8a 3.12.11-r0
python3-pip armv8a 24.0-r0
python3-venv armv8a 3.12.11-r0

Versions and architecture names vary between builds. The presence of all three package names confirms that they were included in the generated image.

tip

If the manifest is not under the expected deployment directory, search the current build as a fallback:

Development host
find build/tmp/deploy/images -type f -name '*.manifest' -print

4. Flash and Verify the Image​

Flash the newly generated image using the instructions for the selected board. After it starts, confirm that ADB lists the expected board with status device:

Development host
adb devices -l

Check that Python and pip are available:

Development host
adb shell 'python3 --version && python3 -m pip --version'

Create a virtual environment and run its Python interpreter:

Development host
adb shell 'python3 -m venv /tmp/yocto-venv && /tmp/yocto-venv/bin/python --version'

If you only need a package temporarily for development or debugging, see Install Packages from a Development Host. For additional image customization options, see the Yocto Project guide to customizing images.