VyOS installation requires to download a VyOS .iso file. That file is a live install image that lets you boot a live VyOS. From that live system you can proceed to the permanent installation on a hard drive or any other type of storage.

Comparison of VyOS image releases

Release Type


Release Cycle

Intended Use

Access to Images

Access to Source

Nightly (Current)

Automatically built from the current branch. Always up to date with cutting edge development but guaranteed to contain bugs.

Every night

Developing VyOS, testing new features, experimenting.



Nightly (Beta)

Automatically built from the development branch and released alongside snapshots. Most likely contains bugs.

Every night

Developing and testing the latest major version under development.




A particularly stable release frozen from nightly each month after manual testing. Still contains experimental code.

Every month until RC comes out

Home labs and simple networks that call for new features.



Release Candidate

Rather stable. All development focuses on testing and hunting down remaining bugs following the feature freeze.

Irregularly until EPA comes out

Labs, small offices and non-critical production systems backed by a high-availability setup.



Early Production Access

Highly stable with no known bugs. Needs to be tested repeatedly under different conditions before it can become the final release.

Irregularly until LTS comes out

Non-critical production environments, preparing for the LTS release.



Long-Term Support

Guaranteed to be stable and carefully maintained for several years after the release. No features are introduced but security updates are released in a timely manner.

Every major version

Large-scale enterprise networks, internet service providers, critical production environments that call for minimum downtime.

Subscribers, contributors, non-profits, emergency services, academic institutions


Hardware requirements

The minimum system requirements are 512 MiB RAM and 2 GiB storage. Depending on your use you might need additional RAM and CPU resources e.g. when having multiple BGP full tables in your system.


Registered Subscribers

Registered subscribers can log into to have access to a variety of different downloads via the “Downloads” link. These downloads include LTS (Long-Term-Support) and associated hot-fix releases, early public access releases, pre-built VM images, as well as device specific installation ISOs.


Building from source

Non-subscribers can always get the LTS release by building it from source. Instruction can be found in the Building VyOS section of this manual. VyOS source code repository is available for everyone at

Rolling Release

Everyone can download bleeding-edge VyOS rolling images from:


Rolling releases contain all the latest enhancements and fixes. This means that there will be new bugs of course. If you think you hit a bug please follow the guide at Issues and Feature requests. To improve VyOS we depend on your feedback!

The following link will always fetch the most recent VyOS build for AMD64 systems from the current branch:

Download Verification

LTS images are signed by VyOS lead package-maintainer private key. With the official public key, the authenticity of the package can be verified. GPG is used for verification.


This subsection only applies to LTS images, for Rolling images please jump to Live installation.

Preparing for the verification

First, install GPG or another OpenPGP implementation. On most GNU+Linux distributions it is installed by default as package managers use it to verify package signatures. If not pre-installed, it will need to be downloaded and installed.

The official VyOS public key can be retrieved in a number of ways. Skip to GPG verification if the key is already present.

It can be retrieved directly from a key server:

gpg --recv-keys FD220285A0FE6D7E

Or it can be accessed via a web browser:

Or from the following block:

Version: GnuPG v1.4.12 (GNU/Linux)


Store the key in a new text file and import it into GPG via: gpg --import file_with_the_public_key

The import can be verified with:

$ gpg --list-keys
pub   rsa4096 2015-08-12 [SC]
uid           [ unknown] VyOS Maintainers (VyOS Release) <[email protected]>
sub   rsa4096 2015-08-12 [E]

GPG verification

With the public key imported, the signature for the desired image needs to be downloaded.


The signature can be downloaded by appending .asc to the URL of the downloaded VyOS image. That small .asc file is the signature for the associated image.

Finally, verify the authenticity of the downloaded image:

$ gpg2 --verify vyos-1.2.1-amd64.iso.asc  vyos-1.2.1-amd64.iso
gpg: Signature made So 14 Apr 12:58:07 2019 CEST
gpg:                using RSA key FD220285A0FE6D7E
gpg: Good signature from "VyOS Maintainers (VyOS Release) <[email protected]>" [unknown]
Primary key fingerprint: 0694 A923 0F51 39BF 834B  A458 FD22 0285 A0FE 6D7E

Live installation


A permanent VyOS installation always requires to go first through a live installation.

VyOS, as other GNU+Linux distributions, can be tested without installing it in your hard drive. With your downloaded VyOS .iso file you can create a bootable USB drive that will let you boot into a fully functional VyOS system. Once you have tested it, you can either decide to begin a Permanent installation in your hard drive or power your system off, remove the USB drive, and leave everything as it was.

If you have a GNU+Linux system, you can create your VyOS bootable USB stick with with the dd command:

  1. Open your terminal emulator.

  2. Find out the device name of your USB drive (you can use the lsblk command)

  3. Unmount the USB drive. Replace X in the example below with the letter of your device and keep the asterisk (wildcard) to unmount all partitions.

$ umount /dev/sdX*
  1. Write the image (your VyOS .iso file) to the USB drive. Note that here you want to use the device name (e.g. /dev/sdb), not the partition name (e.g. /dev/sdb1).

Warning: This will destroy all data on the USB drive!

# dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync
  1. Wait until you get the outcome (bytes copied). Be patient, in some computers it might take more than one minute.

  2. Once dd has finished, pull the USB drive out and plug it into the powered-off computer where you want to install (or test) VyOS.

  3. Power the computer on, making sure it boots from the USB drive (you might need to select booting device or change booting settings).

  4. Once VyOS is completely loaded, enter the default credentials (login: vyos, password: vyos).

If you find difficulties with this method, prefer to use a GUI program, or have a different operating system, there are other programs you can use to create a bootable USB drive, like balenaEtcher (for GNU/Linux, macOS and Windows), Rufus (for Windows) and many others. You can follow their instructions to create a bootable USB drive from an .iso file.


The default username and password for the live system is vyos.

Permanent installation


Before a permanent installation, VyOS requires a Live installation.

Unlike general purpose Linux distributions, VyOS uses “image installation” that mimics the user experience of traditional hardware routers and allows keeping multiple VyOS versions installed simultaneously. This makes it possible to switch to a previous version if something breaks or misbehaves after an image upgrade.

Every version is contained in its own squashfs image that is mounted in a union filesystem together with a directory for mutable data such as configurations, keys, or custom scripts.


Older versions (prior to VyOS 1.1) used to support non-image installation (install system command). Support for this has been removed from VyOS 1.2 and newer releases. Older releases can still be upgraded via the general add system image <image_path> upgrade command (consult Image Management for further information).

In order to proceed with a permanent installation:

  1. Log into the VyOS live system (use the default credentials: vyos, vyos)

  2. Run the install image command and follow the wizard:

vyos@vyos:~$ install image
Welcome to the VyOS install program.  This script
will walk you through the process of installing the
VyOS image to a local hard drive.
Would you like to continue? (Yes/No) [Yes]: Yes
Probing drives: OK
Looking for pre-existing RAID groups...none found.
The VyOS image will require a minimum 2000MB root.
Would you like me to try to partition a drive automatically
or would you rather partition it manually with parted?  If
you have already setup your partitions, you may skip this step

Partition (Auto/Parted/Skip) [Auto]:

I found the following drives on your system:
 sda    4294MB

Install the image on? [sda]:

This will destroy all data on /dev/sda.
Continue? (Yes/No) [No]: Yes

How big of a root partition should I create? (2000MB - 4294MB) [4294]MB:

Creating filesystem on /dev/sda1: OK
Mounting /dev/sda1...
What would you like to name this image? [1.2.0-rolling+201809210337]:
OK.  This image will be named: 1.2.0-rolling+201809210337
Copying squashfs image...
Copying kernel and initrd images...
I found the following configuration files:
Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]:

Copying /opt/vyatta/etc/config.boot.default to sda.
Enter password for administrator account
Enter password for user 'vyos':
Retype password for user 'vyos':
I need to install the GRUB boot loader.
I found the following drives on your system:
 sda    4294MB

Which drive should GRUB modify the boot partition on? [sda]:

Setting up grub: OK
  1. After the installation is completed, remove the live USB stick or CD.

  2. Reboot the system.

vyos@vyos:~$ reboot
Proceed with reboot? (Yes/No) [No] Yes

You will boot now into a permanent VyOS system.

PXE Boot

VyOS can also be installed through PXE. This is a more complex installation method which allows deploying VyOS through the network.


  • Clients (where VyOS is to be installed) with a PXE-enabled NIC

  • DHCP Server

  • TFTP Server

  • Webserver (HTTP) - optional, but we will use it to speed up installation

  • VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3)

  • Files pxelinux.0 and ldlinux.c32 from the Syslinux distribution


Step 1: DHCP

Configure a DHCP server to provide the client with:

  • An IP address

  • The TFTP server address (DHCP option 66). Sometimes referred as boot server

  • The bootfile name (DHCP option 67), which is pxelinux.0

In this example we configured an existent VyOS as the DHCP server:

vyos@vyos# show service dhcp-server
 shared-network-name mydhcp {
     subnet {
         bootfile-name pxelinux.0
         range 0 {

Step 2: TFTP

Configure a TFTP server so that it serves the following:

  • The pxelinux.0 file from the Syslinux distribution

  • The ldlinux.c32 file from the Syslinux distribution

  • The kernel of the VyOS software you want to deploy. That is the vmlinuz file inside the /live directory of the extracted contents from the ISO file.

  • The initial ramdisk of the VyOS ISO you want to deploy. That is the initrd.img file inside the /live directory of the extracted contents from the ISO file. Do not use an empty (0 bytes) initrd.img file you might find, the correct file may have a longer name.

  • A directory named pxelinux.cfg which must contain the configuration file. We will use the configuration file shown below, which we named default.

In the example we configured our existent VyOS as the TFTP server too:

vyos@vyos# show service tftp-server
 directory /config/tftpboot

Example of the contents of the TFTP server:

vyos@vyos# ls -hal /config/tftpboot/
total 29M
drwxr-sr-x 3 tftp tftp      4.0K Oct 14 00:23 .
drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 ..
-r--r--r-- 1 root vyattacfg  25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos
-rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32
-rw-r--r-- 1 root vyattacfg  46K Oct 13 23:24 pxelinux.0
drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg
-r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz

vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg
total 12K
drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 .
drwxr-sr-x 3 tftp tftp      4.0K Oct 14 00:23 ..
-rw-r--r-- 1 root root       191 Oct 14 01:10 default

Example of simple (no menu) configuration file:

vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default

 KERNEL vmlinuz
 APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs

Step 3: HTTP

We also need to provide the filesystem.squashfs file. That is a heavy file and TFTP is slow, so you could send it through HTTP to speed up the transfer. That is how it is done in our example, you can find that in the configuration file above.

First run a web server - you can use a simple one like Python’s SimpleHTTPServer and start serving the filesystem.squashfs file. The file can be found inside the /live directory of the extracted contents of the ISO file.

Second, edit the configuration file of the Step 2: TFTP so that it shows the correct URL at fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs.


Do not change the name of the filesystem.squashfs file. If you are working with different versions, you can create different directories instead.

And third, restart the TFTP service. If you are using VyOS as your TFTP Server, you can restart the service with sudo service tftpd-hpa restart.


Make sure the available directories and files in both TFTP and HTTP server have the right permissions to be accessed from the booting clients.

Client Boot

Finally, turn on your PXE-enabled client or clients. They will automatically get an IP address from the DHCP server and start booting into VyOS live from the files automatically taken from the TFTP and HTTP servers.

Once finished you will be able to proceed with the install image command as in a regular VyOS installation.

Known Issues

This is a list of known issues that can arise during installation.

Black screen on install

GRUB attempts to redirect all output to a serial port for ease of installation on headless hosts. This appears to cause a hard lockup on some hardware that lacks a serial port, with the result being a black screen after selecting the Live system option from the installation image.

The workaround is to type e when the boot menu appears and edit the GRUB boot options. Specifically, remove the:


option, and type CTRL-X to boot.

Installation can be continued as outlined above.