vyos-build, the top level repository that assembles a VyOS network OS image

A distribution is a pile of packages, and this is the pile

The project documentation explains the shape of the thing before it explains the build. VyOS is an open source operating system for network devices, routers and firewalls, and it is a GNU/Linux distribution based on Debian, consisting of multiple packages just like any other distribution. Some packages are taken from upstream, while others are modified or written from scratch by VyOS developers. Every package maintained by the team has its own git repository, which is why the image build is a multi-step process: packages are compiled first, then an ISO is built from the Debian packages and the team's own. This repository is the top level one, containing links to the repositories with the VyOS specific packages, organized as Git submodules, plus the scripts and data used to build those packages and the installation image. The primary language recorded for the repository is Python, the licence is GPL-2.0, and the last push was on 2026-10-13.

This is the top level repository that contains links to repositories with
VyOS specific packages (organized as Git submodules) and scripts and data
that are used for building those packages and the installation image.

Five directories, each with one job

The repository structure section is short and it explains the build better than a paragraph could. The build directory holds temporary files used for the build and for build artifacts. The data directory holds the data required for building the ISO, with the boot splash and configs given as examples. The packages directory can hold arbitrary deb packages which will be embedded into the resulting ISO, and among other things those packages will be the Linux kernel, FRR and Netfilter, which is the list that tells you how much of the network stack is first-party. The scripts directory holds the scripts used for the build process. And the tools directory holds scripts used for maintainer task automation and other purposes, but not during the ISO build process, which is a distinction that keeps the reproducible build path clean.

 * `build/`    Used for temporary files used for the build and for build artifacts
 * `data/`     Data required for building the ISO (e.g. boot splash/configs)
 * `packages/` This directory can hold arbitrary *.deb packages
 * `scripts/`  Scripts that are used for the build process

The build entry point is a catch-all target

The Makefile is a thin wrapper around a single script, and the way it is written is instructive. The default target prints a short message listing the most common target, which is generic, and then a catch-all pattern rule runs the build script with whatever you asked for. The catch-all is the interesting part: the build script is the real interface, and make is a thin pass-through so that the same invocation works from a shell and from a container. The build directory is fixed, and the architecture is detected with the Debian host architecture query, which is why the output image name carries the architecture, since the ISO path is built as a live image with a hybrid suffix for that architecture. There is also an OCI image target, and the path to the newest container tarball is resolved lazily by listing the files and taking the most recent, with a comment explaining that if the lookup finds nothing the checking script performs the same lookup and reports a proper error rather than failing silently.

build_dir := build

ARCH := $(shell dpkg-architecture -qDEB_HOST_ARCH)
ISO_PATH := $(build_dir)/live-image-$(ARCH).hybrid.iso

The test matrix, and what it actually exercises

The test targets are where the real engineering confidence in a network OS comes from, and the list is long: test, test-no-interfaces, test-no-interfaces-no-vpp, test-interfaces, test-vpp, testc, testcvpp, testraid, test-secure-boot, testtpm, testifname, test-ci-qcow2, test-image-update, qemu-live, test-suite and test-oci. Each of those is a configuration of the same machine under test, and the names say what varies: whether the image has interfaces, whether the VPP dataplane is present, RAID, UEFI secure boot, TPM, and the interface naming scheme. The QEMU invocation is tuned to the host rather than hardcoded. The CPU count is the host's processor count capped at four. The memory is 8GB if the host has at least 10GB of RAM and 4GB otherwise, read straight out of the memory information. And the UEFI flag is required on arm64 and aarch64 hosts but optional on amd64, which is the kind of platform detail that a shared script would otherwise get wrong.

Forwarding arguments without breaking make

There is a small piece of make engineering in the test targets that is worth understanding because it trips people up. The test targets forward extra command line arguments to their scripts, such as a match filter passed after a double dash, and the comment explains the trap: those extra words are also goals as far as make is concerned, so without the fix they would fall through to the catch-all pattern rule and run the image build with garbage arguments. The fix uses an eval of the remaining goals so they are absorbed, guarded by a filter that only applies when the first goal is one of the known test targets. It is a two-line guard protecting against a confusing failure, and it is the kind of detail that only appears in a Makefile that has been used by more than one person for a long time.

TEST_TARGETS := test test-no-interfaces test-no-interfaces-no-vpp test-interfaces test-vpp testc testcvpp testraid test-secure-boot testtpm testifname test-ci-qcow2 test-image-update qemu-live test-suite test-oci
ifneq ($(filter $(TEST_TARGETS),$(firstword $(MAKECMDGOALS))),)
$(eval $(filter-out $(firstword $(MAKECMDGOALS)),$(MAKECMDGOALS)):;@:)
endif

Branches named after constellations

The branch model is unusual enough to be memorable and simple enough to be useful. The default branch containing the most recent VyOS code is called rolling, and all new code goes there. When a new LTS release is ready for feature freeze, a new branch is created for the release, and new code from rolling is backported to the release branch as needed. After the 1.2.0 release, branches are named after constellations sorted by area from smallest to largest, and there are 88 of them. The current branches are listed: VyOS 1.4 as sagitta, the Arrow, which is LTS, VyOS 1.3 as equuleus, the Little Horse, also LTS, and VyOS 1.2 as crux, the Southern Cross, which is marked unsupported. The next LTS release will be VyOS 1.5, circinus, the Compasses. The convention has an obvious property, which is that a branch name tells you its age.

* VyOS 1.4: `sagitta` (Arrow) [LTS]
* VyOS 1.3: `equuleus` (Little Horse) [LTS]
* VyOS 1.2: `crux` (Southern Cross) [Unsupported]

Where it fits, and what to check first

The split between this repository and the package repositories is the thing a newcomer has to internalise. The top level holds the orchestration, the submodules hold the first-party code, and the ISO is the output of the two together. A contributor who wants to change routing behaviour is editing a package repository; a contributor who wants to change what ends up on the image is editing here. The documentation also makes the effort explicit, since the online build guide is the canonical instruction set and this repository deliberately keeps a single manual rather than maintaining copies of it in several places, whether you build in a Docker container or natively. The practical checks before a first build are therefore: read the online guide rather than guessing from the Makefile, make sure the submodules are checked out, and pick a branch deliberately, because rolling is where new code lands and the LTS branches are where you backport to. For a reader who only wants to use VyOS, the documentation points elsewhere, to the download and installation instructions, and this repository is not the place to look.

For the most up-to-date documentation, please read the online build guide at
docs.vyos.io

Editorial conclusion

Adopt vyos-build if you are building a VyOS image, testing an ISO against a matrix of configurations, or want to understand how a network OS distribution is assembled from Debian and vendor packages. Skip it if you only want to run VyOS on a router, since the documentation points to the installation guides for that. Verify three things before you start a build: that you have the build environment the online guide describes, since the instructions live in the documentation rather than in the repository; that you understand the submodule layout, because the top level repository contains links rather than the package sources; and which branch you are on, since rolling is where new code goes and the release branches are named after constellations.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. vyos/vyos-build on GitHub