netlab is a Python3 package[1] that runs on Python 3.8 or later on Windows, MacOS, or Linux. It’s a high-level abstraction and orchestration tool that relies on other tools to provide the low-level functionality:

  • VM/container virtualization: VirtualBox (Windows or MacOS), KVM (Linux) or Docker (Linux)

  • Virtualization API: libvirt (used with KVM on Linux)

  • VM/container orchestration: Vagrant or containerlab

  • Configuration deployment: Ansible 2.9.1[2] or later

High-level architecture

If you already have an environment that can be used with netlab, please proceed directly to installing Python package. Otherwise, you’ll have to select the platform you want to use and create your lab environment (including netlab installation).

Selecting the Platform and Low-Level Tools

We have tested netlab with:

  • libvirt/KVM and Vagrant on Ubuntu and Fedora. This combination should work on other Linux distributions.

  • Docker and containerlab on Ubuntu. This combination should also work on other Linux distributions.

  • VirtualBox and Vagrant on MacOS with Intel silicon. The same combination should also work on Windows 10. Ansible works on MacOS; RedHat claims it works (but is not supported) within Windows Subsystem for Linux (WSL).

You can also run netlab in a Ubuntu instance in a public cloud.

When selecting the virtualization environment, consider the following:

  • We are focusing most of our platform development efforts on Linux environments using KVM/libvirt with Vagrant or Docker with containerlab. We have selected Ubuntu as the Linux distribution supported by netlab install command. The installation guide for Ubuntu is thus the most extensive one.

  • Vagrant provider for libvirt supports parallel VM provisioning, resulting in much faster lab creation. An added bonus: if you decide to use Ubuntu, you can use netlab install command to install all the prerequisite software (KVM, libvirt, Vagrant, Docker, containerlab, Ansible).

    Unfortunately, most vendors don’t offer virtual devices packaged as libvirt Vagrant boxes, so you’ll have to build your own boxes.

  • Containers provisioned with containerlab start much faster than virtual machines, but you can get only a few network devices in native container format (Arista cEOS, Nokia SR Linux, Cumulus VX, FRR).

  • VirtualBox is commonly used together with Vagrant as a laptop virtualization solution, resulting in a wider variety of prepackaged boxes (Arista vEOS, Cisco Nexus 9300v, Cumulus VX, Juniper vSRX). The downsides:

    • Slow lab setup due to serial provisioning;

    • No management network (Vagrant uses a weird port NAT to access virtual machines)

    • netlab cannot integrate VirtualBox networking with the external world

Creating the Lab Environment

We have documented how you can set up your lab:


  • If you decide to run the network labs within an Ubuntu VM, create a new VM and use the automated software installation procedure. It’s much easier and safer than trying to install the necessary software on an existing VM.

  • Don’t use VirtualBox on Linux. As you won’t need a GUI to interact with the network devices, we see no reason to do that when there are better alternatives (KVM+libvirt).

If you insist on running network devices directly on your Windows or MacOS (Intel silicon) laptop, try out VirtualBox with Vagrant. This setup won’t be able to run network devices packaged as containers (Arista cEOS, Nokia SR Linux).

Finally, while netlab runs on Apple silicon, you won’t be able to start virtual machines or containers as they’re not available for ARM CPUs. If you own a laptop with Apple silicon, run your labs on an external x86 server (Ubuntu VM running on-premises or in a public cloud, or a bare-metal server)

Building Vagrant Boxes

Installing Python Package

To install netlab on a system that already has the low-level tools installed, use python3 -m pip install networklab. The installation process will install all prerequisite Python packages and create the netlab command.

If you want to get the latest development code or if you want to participate in netlab development, clone the GitHub repository.