Quick Start Guide with Yocto

The standard way to set up a Jetson is the JetPack flow: you flash Jetson Linux (Ubuntu) from an ISO USB stick, following the Quick Start Guide for your developer kit. JetPack delivers NVIDIA’s complete, validated software stack and is an excellent choice for both development and production.

The Yocto Project is an alternative option for teams who prefer to build their own Linux image with the OpenEmbedded build system, choosing exactly which packages are included, integrating the OS build into CI, and reproducing the same image from source on every build. It uses the same Jetson Linux (L4T) and JetPack components under the hood. This guide shows how to get started with the Yocto path on Jetson.

Beginning with JetPack 7.2 (Jetson Linux R39.2), Yocto is an officially supported path on Jetson, developed together with the community OpenEmbedded for Tegra (OE4T) project. The Jetson Yocto recipes live in two OE4T repositories:

• meta-tegra (the Jetson BSP layer) - GitHub: github.com/OE4T/meta-tegra
• tegra-demo-distro (ready-to-use reference images) - GitHub: github.com/OE4T/tegra-demo-distro

You don’t have to build anything to try it. In this guide you’ll download a prebuilt demo-image-reference image and flash it to your Jetson. This Sato/X11 desktop image is the OE4T QA reference image, with comprehensive validation tools, NVIDIA-accelerated container support, and a persistent /data partition that is configured automatically on first boot. It comes from the OE4T tegra-demo-distro wrynose branch.

Supported images

Download the demo-image-reference tegraflash tarball for your target. Use the tarball whose MACHINE name matches your hardware. Do not use a tarball built for a different Jetson module or carrier.

Why Yocto?

The Yocto Project is not a Linux distribution by itself. It is a build framework that produces a distribution tailored to your hardware, package set, and update model. Teams reach for Yocto on Jetson when they need tight control over the OS image that ships in a product: a minimized package set, reproducible builds in CI, Secure Boot, OTA updates, package feeds, and long-term maintenance. For this getting-started guide, you simply consume a prebuilt image, so no build framework knowledge is required.

The end-to-end flow for this guide is short:

What’s in demo-image-reference?

demo-image-reference is a comprehensive QA validation image containing all publicly available test packages supplied by the OE/Yocto recipes. It includes:

• A Sato/X11 desktop, with Weston available for manual launch
• Docker, nvidia-container-toolkit, and NVIDIA registry configuration
• The NVIDIA runtime preconfigured as Docker’s default OCI runtime
• CUDA, cuDNN, TensorRT, VPI4, PVA SDK, Vulkan, and Nsight Systems validation tools
• Open-source test and benchmark utilities such as glmark2, kmscube, lmbench, iperf3, and rt-tests
• An automatically created and mounted /data partition for persistent data and container storage

The older demo-image-full recipe still exists in tegra-demo-distro, but it is no longer the image used to produce the prebuilt JetPack 7.2.1 tarballs.

Prerequisites

Host machine

Use a native x86-64 Ubuntu 24.04 host. Avoid flashing from a virtual machine, container, WSL environment, or through an external USB hub. The low-level USB recovery protocol is sensitive to host USB behavior.

Install the host packages needed by the OE4T flash scripts:

sudo apt update
sudo apt install \
  bash \
  bmap-tools \
  cpp \
  device-tree-compiler \
  gdisk \
  libxml2-utils \
  python3 \
  tar \
  udisks2 \
  usbutils \
  zstd

If you want to monitor a serial console, also install a serial terminal and add your user to the dialout group (log out and back in afterward):

sudo apt install picocom
sudo usermod -aG dialout "$USER"

Prepare the desktop host

On an Ubuntu 24.04 desktop host, disable automatic mounting of removable media before flashing. The Orin flashing flow exposes storage over USB, and desktop automount can interfere with it:

gsettings set org.gnome.desktop.media-handling automount false
gsettings set org.gnome.desktop.media-handling automount-open false

Verify that both commands print false:

gsettings get org.gnome.desktop.media-handling automount
gsettings get org.gnome.desktop.media-handling automount-open

Step 1: Download the image for your device

From the JetPack downloads page (JetPack 7.2.1 / Jetson Linux R39.2.1), under Yocto Images, click the button for your device: Yocto for Jetson AGX Thor, Yocto for Jetson AGX Orin, or Yocto for Jetson Orin Nano. Download the .tegraflash-tar.zst package whose MACHINE matches your hardware (see the Supported images table). Save it to ~/Downloads and leave the filename unchanged.

Step 2: Unpack the flash tarball

Set MACHINE to your target, then unpack the tarball into a fresh directory. Use the value from the table that matches your hardware:

export MACHINE="jetson-agx-thor-devkit"

export MACHINE="p3737-0000-p3701-0005"

export MACHINE="jetson-orin-nano-devkit-nvme"

Then unpack:

mkdir -p ~/jetson-flash
cd ~/jetson-flash
tar xf ~/Downloads/demo-image-reference-${MACHINE}.rootfs.tegraflash-tar.zst

Step 3: Put the Jetson in Recovery Mode

Connect the host to the Jetson’s recovery USB port before running the flash script. The exact port differs per developer kit. The Diagram links open the official Hardware Layout page with annotated photos of the USB port, RECOVERY/RESET buttons, and recovery header.

Enter Force Recovery Mode using the sequence for your developer kit:

Confirm the host can see an NVIDIA recovery-mode USB device:

lsusb -d 0955:

The output should include an APX device, which indicates the Jetson is in recovery mode.

Step 4: Flash the image

From the directory where you unpacked the tarball, run:

sudo ./initrd-flash

The script detects the Jetson in recovery mode, prepares the flash content, and writes the image. By default it flashes both the boot firmware and the configured root filesystem target for the selected MACHINE.

Found Jetson device in recovery mode at USB 3-1
ERR: could not retrieve board information

When flashing completes, bring the device up:

On boot you’ll reach a login prompt. Log in as root (the demo image has no password set by default).

Step 5: Verify the JetPack stack

Once booted, confirm the JetPack components bundled in demo-image-reference are present. Run these on the device (over serial or SSH):

Check the L4T / JetPack release:

cat /etc/nv_tegra_release

Verify Docker with the NVIDIA runtime:

docker info --format 'Default runtime: {{.DefaultRuntime}}'
docker info | grep -i runtime
docker run --rm hello-world

The default runtime should report nvidia. If these commands respond successfully, your Yocto image is up and the JetPack stack is functional. You now have a Sato desktop running on your Jetson with the NVIDIA container runtime ready to use.

Step 6: Verify automatic persistent storage

The JetPack 7.2.1 demo-image-reference image configures persistent storage automatically on first boot. No manual partitioning, formatting, /etc/fstab changes, or Docker configuration are required.

The image uses systemd-repart to create an ext4 partition labeled data, grow it into the available unallocated space, and mount it at /data. Docker and containerd wait for that mount and use these locations by default:

• Docker: /data/docker
• containerd: /data/containerd

The image also uses an overlay filesystem under /data to preserve SSH configuration, NetworkManager connections, and systemd network configuration across OTA updates.

Verify the automatic setup:

findmnt /data
df -hT /data
docker info --format 'Docker root: {{.DockerRootDir}}'
docker info --format 'Default runtime: {{.DefaultRuntime}}'
grep '^root' /etc/containerd/config.toml

The output should show /data mounted as ext4, Docker rooted at /data/docker, containerd rooted at /data/containerd, and nvidia as Docker’s default runtime.

Optional: Serial console

A serial console is not required, but it helps if flashing fails or the device does not boot. Connect at 115200 baud. The host device is commonly /dev/ttyACM0 for CDC-ACM, or /dev/ttyUSB0 for USB-to-TTL adapters:

picocom -b 115200 /dev/ttyACM0

Use Ctrl-A then Ctrl-X to exit picocom. Serial access differs per device:

Troubleshooting

• lsusb -d 0955: shows no device: the Jetson is not in Force Recovery Mode, or the host is connected to the wrong USB port. Re-enter recovery mode from power-off and confirm the recovery USB port.
• Flashing fails with a USB communication error: power cycle the Jetson, enter Force Recovery Mode from power-off, and rerun sudo ./initrd-flash. Also try a different high-quality USB cable and a direct host USB port (no hub).
• The host desktop opens a file browser or mounts storage during flashing: recheck the GNOME automount settings above and close any file-manager windows that opened automatically.
• Keep the logs: if the script fails, keep the generated log.initrd-flash.* file (and the device-logs-* directory for Orin targets) when reporting the issue.

Build your own Yocto image

The prebuilt demo-image-reference is built from source in the OE4T tegra-demo-distro repository. To rebuild it yourself or customize it with your own layer and packages, follow the setup and build steps in the repository README: github.com/OE4T/tegra-demo-distro.

The reference image requires the overlayfs distro feature. For OTA workflows, demo-image-reference-swupdate is the swupdate payload used to deliver demo-image-reference.

References & Next Steps

• JetPack SDK downloads: JetPack 7.2.1 / Jetson Linux R39.2.1, including the Yocto images
• OE4T Flashing Basics (wrynose): the upstream flashing reference
• OE4T tegra-demo-distro wrynose branch and meta-tegra wrynose machine configs
• NVIDIA Jetson Linux R39.2.1: Flashing Support and Quick Start
• Yocto on Jetson: NVIDIA Jetson Linux Developer Guide: the official overview of NVIDIA’s Yocto support

Run your first AI workload

With your Jetson booted and persistent container storage in place, you’re ready to run a containerized AI workload. When you pick an image, match it to your Jetson’s GPU family rather than just its CPU architecture or SBSA support: Thor and Orin are built on different GPU architectures, so their optimized containers are not interchangeable. Use the table below to choose the right image for your device.

On your Yocto-based Jetson, always pick the container tag that matches your GPU family: latest-jetson-thor for Thor (SM110) and latest-jetson-orin for Orin (SM87). These are rolling tags, so the exact Jetson Linux and CUDA versions behind them change over time. On an Orin running the R39.2.1 / JetPack 7.2.1 Yocto image, keep using the Orin tag.