You're reading the development documentation. Release version of the same page is here.

Cisco Nexus 9300v Vagrant Libvirt Boxes

You can download Nexus 9300v virtual disk (.qcow2 file) or Vagrant box for VirtualBox from Vagrant box created for VirtualBox can be mutated into a libvirt box with vagrant-mutate plugin.

Mutated NX-OS 9.3.10 box works well with vagrant-libvirt. You might want to try the same process with other NX-OS software releases before building your own Nexus 9300v box.

Mutating a VirtualBox Box

  • Download nexus9300v.<release>.box file from

  • Check whether the vagrant-mutate plugin is installed with vagrant plugin list

  • If needed, install the vagrant-mutate plugin with vagrant plugin install vagrant-mutate

  • Install virtualbox version of the Nexus 9300v Vagrant box with vagrant box add <box-filename> --name cisco/nexus9300v

  • Mutate the Nexus 9300v box with vagrant mutate cisco/nexus9300v libvirt

  • Verify that you got the desired Vagrant box installed with vagrant box list

  • Optionally remove the virtualbox version of the Vagrant box with vagrant box remove cisco/nexus9300v --provider virtualbox

Building a Cisco Nexus 9300v Vagrant Libvirt Box

Cisco Nexus 9300v is supported by the netlab libvirt package command. To build an Nexus 9300v box:

  • Create an empty directory on a Ubuntu machine with libvirt and Vagrant.

  • Download Nexus 9300v disk image (.qcow2 file) into that directory

  • Execute netlab libvirt package nxos virtual-disk-file-name and follow the instructions


  • The box building process generates a random device serial number that will be used by all Nexus 9300v devices created from the Vagrant box. As NX-OS uses device serial number as its DHCP client ID, you might experience problems starting a lab with more than one Nexus 9300v device on newer versions of KVM/libvirt. The workaround-of-last-resort is setting libvirt batch_size to 1.

  • The ‌netlab libvirt package nxos command has been tested on Ubuntu 20.04 LTS and 22.04 LTS and might not work on other Linux distros.

  • On Ubuntu 22.04 LTS, libvirt-qemu user needs read and execute access to the VM disk file. It’s easiest if you create Vagrant boxes in a subdirectory of the /tmp directory.


See Cisco Nexus OS Caveats if you want to run NX OS 10.1 or later

Initial Device Configuration

During the box-building process (inspired by this solution) you’ll have to copy-paste initial device configuration. netlab libvirt config nxos command displays the build recipe:

Creating initial configuration for Cisco Nexus OS 9.3, 10.1 and 10.2

* If faced with annoying power-on auto provisioning (POAP) prompt, answer "skip"
* Login with username 'admin', no password
* Go into enable mode, enter configuration mode
* Copy-paste the following configuration

feature bash-shell
username admin password admin!
no ip domain-lookup
username vagrant password vagrant role network-admin
username vagrant sshkey ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA6NF8iallvQVp22WDkTkyrtvp9eWW6A8YVr+kz4TjGYe7gHzIw+niNltGEFHzD8+v1I2YJ6oXevct1YeS0o9HZyN1Q9qgCgzUFtdOKLv6IedplqoPkcmF0aYet2PkEDo3MlTBckFXPITAMzF8dJSIFo9D8HfdOV0IAdx4O7PtixWKn5y2hMNG0zQPyUecp4pzC6kivAIhyfHilFR61RGL+GPXQ2MWZWFYbAGjyiYJnAmCP3NOTd0jMZEnDkbUvxhMmBYSdETk1rRgm+R4LOzFUGaHqHDLKLX+FIPKcF96hrucXzcWyLbIbEgE98OHlnVYCzRdK8jlqm8tehUc9c9WhQ==
feature nxapi
feature scp-server
line vty
  exec-timeout 0
interface mgmt0
  ip address dhcp
  no shutdown

* Find NXOS image name in bootflash (dir bootflash:)
* Configure boot image with 'boot nxos bootflash:/_imagename_'

WARNING: Without configuring the boot image, the Vagrant box stops at the
"loader >" prompt

When you're done configuring the device:

* Exit configuration mode
* Execute 'copy running startup'
* Disconnect from console (ctrl-] usually works). Do not do anything else
  (like reloading the box).

Mutating Virtualbox Boxes

Cisco Nexus 9300v is available as Virtualbox box. To use that box with vagrant-libvirt:


You might experience weird Vagrant errors when starting mutated Nexus OS boxes with ‌netlab up command. Building a box yourself usually solves that problem.