Skip to content

Containerlab - your network-centric labs with a Docker UX#

With the growing number of containerized Network Operating Systems (NOS) grows the demand to easily run them in the user-defined, versatile lab topologies. Unfortunately, container runtimes alone and tools like docker-compose are not a particularly good fit for that purpose, as they do not allow a user to easily create p2p connections between the containers.

Containerlab provides a framework for orchestrating networking labs with containers. It starts the containers, builds a virtual wiring between them to create a topology of users choice and then manages a lab lifecycle.

Containerlab focuses on containerized Network Operating Systems such as:

In addition to native containerized NOSes, containerlab can launch traditional virtual-machine based routers using vrnetlab integration:

  • Nokia virtual SR OS (vSim/VSR)
  • Juniper vMX
  • Cisco IOS XRv
  • Arista vEOS

And, of course, containerlab is perfectly capable of wiring up arbitrary linux containers which can host your network applications, virtual functions or simply be a test client. With all that, containerlab provides a single IaaC interface to manage labs which can span contain all the needed variants of nodes:

The WHY#

As it often happens, was created by engineers to address their needs.

In containerlab's case the need was simple - to be able to create networking topologies with containerized Network Operating Systems

As you might know, the off-the-shelf tools like docker-compose are not really fit-for-purpose of defining a multi-interfaced containers, therefore many of us created the bespoke bash scripts ruling a web of veth pairs between containers.

Containerlab solves this, and helps many other pain points you might have seen while running your labs.


Containerlab is what docker-compose would be if it was created with networking topologies in mind.

We use so-called clab files to define a topology that is then deployed by containerlab anywhere, where docker runs without any 3rd party dependencies.


The clab file is a YAML in disguise, it offers a way to define your topology top-to-bottom.

Balancing between the simplicity, conventionality and expressiveness it allows users to define topologies that are both easy to read/write and yet are not limited in features)

name: srlceos01

      kind: srl
      image: srlinux:20.6.3-145
      license: license.key
      kind: ceos
      image: ceos:4.25.0F

    - endpoints: ["srl:e1-1", "ceos:eth1"]

The HOW#

This clab file is all that is needed to spin up a lab of the two interconnected nodes - Nokia SR Linux and Arista cEOS.

Yes, that is all that's needed. No bulky emulators, no bespoke datapaths. A pure container-based lab powered by linux networking primitives.

That is what you get:


All the heavy lifting of launching the containerized NOS is abstracted by containerlab kinds. It knows how to start SR Linux and cEOS. Just tell it which kind you need and what image to use

No need to keep handy those endless ENV vars or lengthy commands.

Interconnecting the nodes is as easy as writing a string of text. Tell containerlab which interfaces you want to be interconnected, and it will create the veth pairs blazingly fast.


And surely enough, that is just the tip of an iceberg, containerlab packs a ton of features which I won't repeat here, as they are all mentioned in the docs site we carefully maintain.

Multivendor capabilities#

Arista cEOS#

Although containerlab was born in Nokia, it is now truly multivendor.

Arista folks reading this? Here is a full blown support for cEOS

Run cEOS as a first class citizen, it even makes cEOS to respect the docker assigned IP address.

Juniper cRPD#

We don't pick sides in our choice of containerized NOS support, so Juniper cRPD is as welcome as any other NOS.



Yes, SONiC is there as well and we spent some time to make it beautifully integrated and start up just as any other NOS.

A perfect candidate to be paired with Nokia SR Linux and see a modern DC interop use cases through and through.



Coming from the free OSS NOS camp? FRR is also under containerlab umbrella.

Basically, any Linux based NOS that you can image will be able to be run by containerlab, as it is agnostic to the packages inside the linux container.

Containerlab is extensible, and if anything that is dear to your heart is missing it definitely can be added.

Network node + regular containers#

Also remember that the same clab file can really be like docker-compose file.

  • ✅ Need to bind mount files/dirs to your network node
  • ✅ Want to expose a port to a container host
  • ✅ Maybe set ENV vars
  • ✅ Or change/augment the CMD the node runs

I am repeating myself, but can't stress this enough, containerlab clab files are a mix of a docker-compose and some networking stardust. That means that you can define a topology that will have both linux containers and network nodes.

A perfect example - a telemetry lab.


The above topology is defined in a single clab file that has your networking nodes and regular linux container defined.

A single gittable, versionable lightweight text file defines a ready-made topology that is spinnable in 15 seconds.

What about my VM-based routers?#

I can imagine how @ioshints says that this container-ish thingy can't stand a chance vs real-deal qcow2 packaged VMs.

Yes, a valid concern, but we are lucky that guys like @plajjan did some splendid work that we leveraged in containerlab.

Watch my hands.

Containerlab can run classic VMs like Nokia SR OS, Cisco IOS-XR, Juniper vMX, Arista vEOS in the container packaging. Yes, defined in the same clab file.

This is possible by using our adapted version of vrnetlab project -


name: vr04

      kind: srl
      image: srlinux:20.6.3-145
      license: license.key
      kind: vr-xrv9k
      image: vr-xrv:7.2.1

    - endpoints: ["srl:e1-1", "xrv9k:eth1"]

With this you can turn any EVE-NG or GNS lab that you have into a clab file. By packaging your routers into container images you can push them into a registry and enjoy your labs with a docker UX.

Total control about reproducibility.


In fact, in Nokia many engineers already transitioned from virsh/EVE/GNS to containerlab and they helped us refine containerlab to make it play nicely with classic VM-based products.

The benefits of treating a router VM as a container are quite compelling.

Sharing lab access#

Ok, so in the same containerlab file we can

  • run any linux container
  • run most popular containerized NOSes
  • run VM-based routers

what else?

Globe with meridians here goes the story about our collab with @atoonk and his @mysocketio service

There is a thing about 'em labs. They usually run in a closed, isolated environments, with a handful of ppl having access to it.

But quite often you find yourself in need to share access to this lab. And then it becomes a battle of a hundred SSH tunnels and exposed credentials.

By integrating mysocketio service into containerlab we achieved an on-demand, stable & secure and lab access sharing.

Check out this short video that explains the concepts:

Just like this, adding a single line to your node definition, you make it available via Internet over the anycast network with optional strict OAuth rules for a fine grained access control.


What are the use cases?#

The usecases where containerlab can shine are not only limited to labs.

It is a perfect demo tool, you have a guarantee that your lab will run just like it always was thanks to strict versioning and immutable container images. With a very small footprint, requiring only Docker

Another domain where we see containerlab be of a great help is CI/CD. Github Actions and Gitlab CI both have docker installed on their runners, so you can launch topologies and test them in your CI easily.


Any examples?#

Definitely, we also launched a satellite repo for containerlab based labs -

This catalog is meant to be an open collection of labs built with containerlab. Anything you build with containerlab I will gladly feature there with full attribution to an author.

You will likely find more use cases that fit your need, so give a nice spin and let us know how it goes.

Special thanks#

I want to thank @WHenderickx and @Karimtw_ who started this thing and created the core architecture.

Then our internal users and contributors for always providing feedback and thus making containerlab better. It was a truly team work.

A special kudos goes to @networkop1 who is always ahead of time and had a similar tool (docker-topo) created years ago. We took inspiration from it when were creating the containerlab topo file schema.

Found this awesome, do not hesitate to star our repo - as a way of saying thanks.

Want to contribute? That is awesome and appreciated!

PS. The original announcement was made via this tweet-series.