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-full image and flash it to your Jetson. demo-image-full is a desktop (Sato/X11) image that already includes nvidia-docker and the Multimedia API samples, a good way to see what a Yocto-based Jetson image looks like. It comes from the OE4T tegra-demo-distro wrynose branch.

Supported images

Download the demo-image-full 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-full?

The tegrademo distro from OE4T ships several reference image recipes. demo-image-full is the most complete one:

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 / Jetson Linux R39.2), 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-full-${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-full 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 | grep -i runtime
docker run --rm --runtime nvidia hello-world

If these respond, your Yocto image is up and the JetPack stack is functional. You now have a Sato desktop running on your Jetson with containers and the multimedia samples ready to use.

Step 6: Set up persistent storage for Docker containers

lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINTS
fdisk -l /dev/nvme0n1

lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINTS
fdisk -l /dev/mmcblk0

lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINTS
fdisk -l /dev/nvme0n1

fdisk /dev/nvme0n1

fdisk /dev/mmcblk0

fdisk /dev/nvme0n1

reboot

export DATA_PARTITION=/dev/nvme0n1p13

export DATA_PARTITION=/dev/mmcblk0p17

export DATA_PARTITION=/dev/nvme0n1p17

lsblk -f "$DATA_PARTITION"
mkfs.ext4 -L JETSON_DATA "$DATA_PARTITION"

mkdir -p /data
DATA_UUID=$(blkid -s UUID -o value "$DATA_PARTITION")
echo "UUID=$DATA_UUID /data ext4 defaults,nofail 0 2" >> /etc/fstab
mount -a

findmnt /data
df -hT /data

systemctl stop docker.socket docker containerd

mkdir -p /data/docker /data/containerd /etc/containerd
cp /etc/docker/daemon.json /etc/docker/daemon.json.before-data

cat > /etc/docker/daemon.json <<'EOF'
{
  "data-root": "/data/docker",
  "runtimes": {
    "nvidia": {
      "args": [],
      "path": "nvidia-container-runtime"
    }
  }
}
EOF

cat > /etc/containerd/config.toml <<'EOF'
version = 2
root = "/data/containerd"
state = "/run/containerd"
EOF

systemctl start containerd docker

findmnt /data
docker info --format 'Docker root: {{.DockerRootDir}}'
docker info | grep -i 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-full is built from source on 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.

References & Next Steps

• JetPack SDK downloads: JetPack 7.2 / Jetson Linux R39.2, 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: 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 / JetPack 7.2 Yocto image, keep using the Orin tag.