Installation#

Containerlab is distributed as a Linux deb/rpm/apk package for amd64 and arm64 architectures and can be installed on any Debian- or RHEL-like distributive in a matter of a few seconds.

Pre-requisites#

The following requirements must be satisfied to let containerlab tool run successfully:

• A user should have sudo privileges to run containerlab.
• A Linux server/VM¹ and Docker installed.
• Load container images (e.g. Nokia SR Linux, Arista cEOS) that are not downloadable from a container registry. Containerlab will try to pull images at runtime if they do not exist locally.

Quick setup#

The easiest way to get started with containerlab is to use the quick setup script that installs all of the following components in one go (or allows to install them separately):

• docker (docker-ce), docker compose
• Containerlab (using the package repository)
• gh CLI tool

The script has been tested on the following OSes:

• Ubuntu 20.04, 22.04, 23.10, 24.04
• Debian 11, 12
• Red Hat Enterprise Linux 9
• CentOS Stream 9
• Fedora Server 40 (should work on other variants of Fedora)
• Rocky Linux 9.3, 8.8 (should work on any 9.x and 8.x release)

To install all components at once, run the following command on any of the supported OSes:

curl -sL https://containerlab.dev/setup | sudo -E bash -s "all"

To complete installation and enable sudo-less docker command execution, please run newgrp docker or logout and log back in.

To install an individual component, specify the function name as an argument to the script. For example, to install only docker:

curl -sL https://containerlab.dev/setup | sudo -E bash -s "install-docker"

If you don't have your own shell configuration and want to have a slightly better bash PS1 prompt you can also run this script:

curl -sL https://containerlab.dev/setup | sudo -E bash -s "setup-bash-prompt"

Log out and log back in to see the new two-line prompt in action:

[*]─[clab]─[~]
└──>

Install script#

Containerlab can be installed using the installation script that detects the operating system type and installs the relevant package:

bash -c "$(curl -sL https://get.containerlab.dev)"

bash -c "$(curl -sL https://get.containerlab.dev)" -- -v 0.10.3

# with wget
bash -c "$(wget -qO - https://get.containerlab.dev)"

Since the installation script uses GitHub API, users may hit the rate limit imposed by GitHub. To avoid this, users can pass their personal GitHub token as an env var to the installation script:

GITHUB_TOKEN=<your token> bash -c "$(curl -sL https://get.containerlab.dev)"

Package managers#

It is possible to install official containerlab releases via public APT/YUM repository.

echo "deb [trusted=yes] https://netdevops.fury.site/apt/ /" | \
sudo tee -a /etc/apt/sources.list.d/netdevops.list

sudo apt update && sudo apt install containerlab

sudo yum-config-manager --add-repo=https://netdevops.fury.site/yum/ && \
echo "gpgcheck=0" | sudo tee -a /etc/yum.repos.d/netdevops.fury.site_yum_.repo

sudo yum install containerlab

sudo dnf config-manager -y --add-repo "https://netdevops.fury.site/yum/" && \
echo "gpgcheck=0" | sudo tee -a /etc/yum.repos.d/netdevops.fury.site_yum_.repo

sudo dnf install containerlab

sudo dnf config-manager addrepo --set=baseurl="https://netdevops.fury.site/yum/" && \
echo "gpgcheck=0" | sudo tee -a /etc/yum.repos.d/netdevops.fury.site_yum_.repo

sudo dnf install containerlab

# manually install latest release with package managers
LATEST=$(curl -s https://github.com/srl-labs/containerlab/releases/latest | sed -e 's/.*tag\/v\(.*\)\".*/\1/')
# with yum
yum install "https://github.com/srl-labs/containerlab/releases/download/v${LATEST}/containerlab_${LATEST}_linux_amd64.rpm"
# with dpkg
curl -sL -o /tmp/clab.deb "https://github.com/srl-labs/containerlab/releases/download/v${LATEST}/containerlab_${LATEST}_linux_amd64.deb" && dpkg -i /tmp/clab.deb

# install specific release with yum
yum install https://github.com/srl-labs/containerlab/releases/download/v0.7.0/containerlab_0.7.0_linux_386.rpm

The package installer will put the containerlab binary in the /usr/bin directory as well as create the /usr/bin/clab -> /usr/bin/containerlab symlink. The symlink allows the users to save on typing when they use containerlab: clab <command>.

Windows#

Containerlab runs on Windows powered by Windows Subsystem Linux (aka WSL), where you can run Containerlab directly or in a Devcontainer. Open up Containerlab on Windows documentation for more details.

Apple macOS#

Running containerlab on macOS is possible both on ARM (M1/M2/M3/etc) and Intel chipsets. For a long time, we had many caveats around M-chipsets on Macs, but with the introduction of ARM64-native NOSes like Nokia SR Linux and Arista cEOS, powered by Rosetta emulation for x86_64-based NOSes, it is now possible to run containerlab on ARM-based Macs.

Since we wanted to share our experience with running containerlab on macOS in details, we have created a separate - Containerlab on macOS - guide.

Container#

Containerlab is also available in a container packaging. The latest containerlab release can be pulled with:

docker pull ghcr.io/srl-labs/clab

To pick any of the released versions starting from release 0.19.0, use the version number as a tag, for example, docker pull ghcr.io/srl-labs/clab:0.19.0

Since containerlab itself deploys containers and creates veth pairs, its run instructions are a bit more complex, but still, it is a copy-paste-able command.

For example, if your lab files are contained within the current working directory - $(pwd) - then you can launch containerlab container as follows:

docker run --rm -it --privileged \
    --network host \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /var/run/netns:/var/run/netns \
    -v /etc/hosts:/etc/hosts \
    -v /var/lib/docker/containers:/var/lib/docker/containers \
    --pid="host" \
    -v $(pwd):$(pwd) \
    -w $(pwd) \
    ghcr.io/srl-labs/clab bash

Within the started container you can use the same containerlab deploy/destroy/inspect commands to manage your labs.

docker run --rm -it --privileged \
# <run options omitted>
-w $(pwd) \
ghcr.io/srl-labs/clab deploy -t somelab.clab.yml

Manual installation#

If the linux distributive can't install deb/rpm packages, containerlab can be installed from the archive:

# get the latest available tag
LATEST=$(curl -s https://github.com/srl-labs/containerlab/releases/latest | \
       sed -e 's/.*tag\/v\(.*\)\".*/\1/')

# download tar.gz archive
curl -L -o /tmp/clab.tar.gz "https://github.com/srl-labs/containerlab/releases/download/v${LATEST}/containerlab_${LATEST}_Linux_amd64.tar.gz"

# create containerlab directory
mkdir -p /etc/containerlab

# extract downloaded archive into the containerlab directory
tar -zxvf /tmp/clab.tar.gz -C /etc/containerlab

# (optional) move containerlab binary somewhere in the $PATH
mv /etc/containerlab/containerlab /usr/bin && chmod a+x /usr/bin/containerlab

Upgrade#

To upgrade containerlab to the latest available version issue the following command²:

sudo -E containerlab version upgrade

This command will fetch the installation script and will upgrade the tool to its most recent version. In case of GitHub rate limit, provide GITHUB_TOKEN env var with your personal GitHub token to the upgrade command.

Or leverage apt/yum utilities if containerlab repo was added as explained in the Package managers section.

From source#

To build containerlab from source:

goreleaser --snapshot --skip-publish --rm-dist

Uninstall#

To uninstall containerlab when it was installed via installation script or packages:

apt remove containerlab

yum remove containerlab

SELinux#

When SELinux set to enforced mode containerlab binary might fail to execute with Segmentation fault (core dumped) error. This might be because containerlab binary is compressed with upx and selinux prevents it from being decompressed by default.

To fix this:

sudo semanage fcontext -a -t textrel_shlib_t $(which containerlab)
sudo restorecon $(which containerlab)

or more globally:

sudo setsebool -P selinuxuser_execmod 1