Qemu is one of the emulator you can use with GNS3. It is the most versatile emulator we provide support for.
The qemu we ship with the windows bundle is quite old and one can expect bugs and other problems to arise. However in most situations, it works just fine. We cannot yet provide an up to date qemu for windows, if you want to contribute, you will have to build qemu on Windows yourself and integrate our patches (see below).

Please refer to the Qemu documentation for installing and using Qemu: http://wiki.qemu.org/Manual

Find images

We provide a limited set of images, it's available as a convenience for our users. Recent versions of Qemu are very stable and able to emulate hardware accurately, so many operating systems are available, you may want to install OpenBSD in a networking environment for the multiples networking daemons and tools it provide, it will work out of the box in many situations.

Images can be found here:

- http://www.gns3.net/appliances/
- http://wiki.qemu.org/Testing
- ...

Or you can create your own image using qemu-img (see below).

Configure GNS3 to use your Qemu image

You can configure QEMU using the Edit -> Preferences -> Qemu menu.


General Settings

Basic options

- Path to qemuwrapper: Should be correct by default, you may have to change it if you upgrade GNS3 and still use your old configuration, to start with a blank configuration, delete the gns3.ini file).
- Working directory: A temporary directory where we store qemu temporary images (SWAP and FLASH).
- Path to qemu/qemu-img: it should always be 'qemu' or 'qemu.exe', however you might want to change it, for example if you have several qemu versions on your system
- Qemuwrapper port: change it if you cannot use the default port
- Base console port / Base UDP port: base port used for console and networking, will increment at each instance, if you change it you should have a good reason

Advanced options

- IP/host binding: choose on what interface you want the wrapper to tell the emulators to bind to
- Enable QemuManager: with yes, it will execute qemuwrapper itself with the correct port number and connect to it. With no, it will let you execute the wrapper yourself, do that if you experience problems with the wrapper and want to know why or if the wrapper is on a remote host
- Send qemu paths to external wemuwrapper: when qemuwrapper is started by hand, choose if you want to send the paths to it (local) or if you prefer it to try and determine the correct paths (external wrapper or GUI misconfiguration)
- External qemuwrapper: register any external qemuwrapper you want and choose to use it or not, you should be careful when using this feature as it requires qemu hosts to communicate with dynamips instances on other hosts.

Qemu Guest

In this menu, you can register several images to use with Qemu.

Preferences->Qemu->Qemu Guest

In this example, two images are configured, you can choose how many Network Interface Cards will be available with your Qemu host.
On the main window, if you registered more than 1 Qemu guest, you will have to choose which guest to use each time you drag and drop a Qemu node on the scene.

Other guests

The other tabs are here to configure specific images to use with special Qemu instances: JunOS/PIX/ASA/IDS.


Old patches: version 1.0.50<

Dynamips communicates with GNS3 using an UDP tunnel, this was done way before we took over the project (dynamips-community) and at that time, the most straight forward way to integrate easily qemu was to patch it to use the same protocol. Each emulator would use this protocol and code complexity can be significantly decreased as a result.
The patches are available here, you should apply this file with:

git apply TUNNEL.patch

Older versions of the patch can be found on the forum.

Please note that the old patch uses a deprecated qemu syntax, and it's not guaranteed to work in the future.

New patches: version 1.0.50>

New patches were submitted to qemu-devel towards the end of 2011 and were successfully integrated. They have been rewritten to match the current qemu net framework.
GNS3 has been patched to support the new syntax:

  • use -device instead of -net nic
  • -netdev compatibilty
  • -net[dev] socket,udp=dhost:dport,localaddr=shost:sport will connect 2 UDP endpoints

The new syntax doesn't rely anymore on VLANs, however, the current qemu net framework still extensively uses a VLAN logic. The packet dump feature net dump is not compatible with the newer and not-deprecated syntax. Some work is ongoing in fixing this, see issue #4 for more details.

Default behavior

By default, GNS3 will use the new syntax, however if you decide you really need the -dump feature you could use a patched Qemu and set qemuprotocol to 0 in qemuwrapper.py.

Image format

It is important to format your qemu hard drive images files using qcow2 image format. Recent work has introduced new features in GNS3 that will work best with this file format. You are free to use any other file format however, but don't expect some features to work:

  • Smaller file size, even on filesystems which don't support holes (i.e. sparse files)
  • Copy-on-write support, where the image only represents changes made to an underlying disk image
  • Snapshot support, where the image can contain multiple snapshots of the images history
  • Optional zlib based compression
  • Optional AES encryption

Create a qcow2 disk image

qemu-img create -f qcow2 os.qcow2 2G

Boot and install the operating system:

qemu -cdrom install.iso os.qcow2

You can convert disk image formats afterwards using the qemu-img convert command.


In the future, GNS3 will attempt to take a snapshot of your VM state when stopping it within the GUI.
It is faster to take snapshots when using a read-only disk image.


Relies on the qcow2 file format, if you don't use such a file format expect your state to be lost when the vm is powered off.
It takes time to make a snapshot.