Install GNS3 Network Simulator on Debian 13/12

GNS3 (Graphical Network Simulator-3) is an open-source network emulator that lets you design, build, and test network topologies without physical hardware. It supports Cisco IOS, Juniper, MikroTik, and many other vendor images through Dynamips, QEMU, and Docker. Network engineers use GNS3 for lab practice, certification prep (CCNA, CCNP, CCIE), proof-of-concept testing, and network automation development.

This guide covers GNS3 installation on Debian 13 (Trixie) and Debian 12 (Bookworm) with all required dependencies.

Prerequisites

• Debian 13 or Debian 12 system (desktop installation recommended for the GUI)
• Minimum 4 GB RAM (8 GB+ recommended for running multiple appliances)
• At least 20 GB free disk space
• User account with sudo privileges
• CPU with virtualization support (Intel VT-x or AMD-V) enabled in BIOS
• Active internet connection

Step 1: Update the System

Start with a full system update to ensure all packages are current.

sudo apt update && sudo apt upgrade -y

Step 2: Install Required Dependencies

GNS3 requires several system packages. Install them in one pass.

sudo apt install -y python3 python3-pip python3-venv python3-pyqt5 python3-pyqt5.qtsvg \
  python3-pyqt5.qtwebsockets python3-setuptools python3-dev \
  qemu-system-x86 qemu-kvm qemu-utils libvirt-daemon-system virtinst \
  bridge-utils libpcap-dev libelf-dev cmake git gcc g++ \
  vpcs dynamips ubridge telnet xterm wireshark \
  cpu-checker curl ca-certificates

Verify that KVM acceleration is available on your system.

kvm-ok

Expected output:

INFO: /dev/kvm exists
KVM acceleration can be used

If KVM is not available, enable virtualization in your BIOS/UEFI settings and reboot.

Step 3: Install GNS3 Server and GUI

The recommended approach on Debian is to install GNS3 using pip inside a Python virtual environment. This avoids conflicts with system Python packages and gives you control over the GNS3 version.

Create and activate a virtual environment.

python3 -m venv ~/gns3-venv
source ~/gns3-venv/bin/activate

Install GNS3 server and GUI.

pip install gns3-server gns3-gui

Verify the installation.

gns3server --version
gns3 --version

Both commands should return the same version number.

Step 4: Install Dynamips

Dynamips is the Cisco IOS emulator that GNS3 uses for IOS router images. If it was not available from the Debian repositories in Step 2, build it from source.

cd /tmp
git clone https://github.com/GNS3/dynamips.git
cd dynamips
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install

Verify Dynamips is working.

dynamips --version

Step 5: Install uBridge

uBridge creates network connections between GNS3 appliances. If it was not installed from the repository in Step 2, build it from source.

cd /tmp
git clone https://github.com/GNS3/ubridge.git
cd ubridge
make -j$(nproc)
sudo make install

Verify installation.

ubridge --version

Step 6: Install VPCS

VPCS (Virtual PC Simulator) provides lightweight simulated PCs for basic connectivity testing. If it was not installed from the repository, build from source.

cd /tmp
git clone https://github.com/GNS3/vpcs.git
cd vpcs/src
./mk.sh
sudo cp vpcs /usr/local/bin/

Verify VPCS.

vpcs --version

Step 7: Configure User Permissions

Add your user to the required groups for KVM, libvirt, Wireshark, and ubridge access.

sudo usermod -aG kvm,libvirt,wireshark $(whoami)

Allow ubridge to capture packets without root privileges.

sudo setcap cap_net_admin,cap_net_raw+ep $(which ubridge)

Log out and back in for group changes to take effect. Confirm your group membership.

groups

The output should include kvm, libvirt, and wireshark.

Step 8: Create a GNS3 Launcher Script

Since GNS3 is installed in a virtual environment, create a launcher script for convenience.

cat << 'EOF' | sudo tee /usr/local/bin/gns3-launcher
#!/bin/bash
source ~/gns3-venv/bin/activate
gns3 "$@"
EOF
sudo chmod +x /usr/local/bin/gns3-launcher

Create a desktop entry so GNS3 appears in your application menu.

cat << EOF | sudo tee /usr/share/applications/gns3.desktop
[Desktop Entry]
Name=GNS3
Comment=GNS3 Network Simulator
Exec=/usr/local/bin/gns3-launcher
Icon=gns3
Type=Application
Categories=Education;Network;
Terminal=false
EOF

Step 9: Start and Configure GNS3

Launch GNS3 from the terminal or application menu.

source ~/gns3-venv/bin/activate
gns3

On first launch, the Setup Wizard appears. Select “Run appliances on my local computer” for a standalone setup. The wizard checks for installed components – Dynamips, QEMU, VPCS, and uBridge should all show green checkmarks.

Key settings to verify in Edit – Preferences:

• Server – Local server should be bound to 127.0.0.1 on port 3080
• Dynamips – Path should point to /usr/local/bin/dynamips or /usr/bin/dynamips
• QEMU – QEMU binary paths auto-detected from /usr/bin/qemu-system-x86_64
• VPCS – Path should point to /usr/local/bin/vpcs or /usr/bin/vpcs
• uBridge – Path should point to /usr/local/bin/ubridge or /usr/bin/ubridge

Step 10: Import Appliances and IOS Images

GNS3 supports importing appliance templates from the GNS3 marketplace. To import an appliance:

1. Download the .gns3a appliance file from https://gns3.com/marketplace/appliances
2. In GNS3, go to File – Import Appliance
3. Select the downloaded .gns3a file
4. Follow the prompts to provide the required disk image or IOS file
5. The appliance appears in the left sidebar under the appropriate device category

For Cisco IOS images (used with Dynamips), you need your own legally obtained IOS images. Place them in ~/GNS3/images/IOS/. Then add them through Edit – Preferences – Dynamips – IOS Routers – New.

For QEMU-based appliances (Cisco IOSv, ASAv, Juniper vMX, MikroTik CHR), place disk images in ~/GNS3/images/QEMU/.

Step 11: Configure Firewall (Optional)

If you run a firewall on your Debian system, allow GNS3 server traffic.

For nftables (default on Debian 12/13):

sudo nft add rule inet filter input tcp dport 3080 accept
sudo nft add rule inet filter input udp dport 10000-30000 accept

For ufw:

sudo apt install -y ufw
sudo ufw allow 3080/tcp comment "GNS3 server"
sudo ufw allow 10000:30000/udp comment "GNS3 console ports"
sudo ufw reload

Port 3080 is used by the GNS3 server API. The UDP range 10000-30000 covers console connections to running appliances.

Step 12: Run GNS3 Server as a systemd Service (Optional)

If you want the GNS3 server to start automatically at boot, create a systemd unit file. Replace yourusername with your actual username.

sudo tee /etc/systemd/system/gns3-server.service << EOF
[Unit]
Description=GNS3 Server
After=network.target

[Service]
Type=simple
User=yourusername
Group=yourusername
ExecStart=/home/yourusername/gns3-venv/bin/gns3server --local
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

Enable and start the service.

sudo systemctl daemon-reload
sudo systemctl enable --now gns3-server
sudo systemctl status gns3-server

The server should show active (running). Test the API endpoint.

curl -s http://127.0.0.1:3080/v2/version | python3 -m json.tool

Troubleshooting

GNS3 GUI fails to start with Qt errors

If you see errors related to Qt or PyQt5, ensure the system PyQt5 packages are installed and the virtual environment can access them.

sudo apt install -y python3-pyqt5 python3-pyqt5.qtsvg python3-pyqt5.qtwebsockets

Recreate the virtual environment with system package access.

rm -rf ~/gns3-venv
python3 -m venv --system-site-packages ~/gns3-venv
source ~/gns3-venv/bin/activate
pip install gns3-server gns3-gui

uBridge permission denied errors

If appliances fail to start with ubridge permission errors, reapply the capabilities.

sudo setcap cap_net_admin,cap_net_raw+ep $(which ubridge)

Verify the capabilities are set.

getcap $(which ubridge)

KVM acceleration not available

Check if the KVM modules are loaded.

lsmod | grep kvm

You should see kvm_intel or kvm_amd along with kvm. If missing, load them manually.

# For Intel CPUs
sudo modprobe kvm_intel

# For AMD CPUs
sudo modprobe kvm_amd

If modprobe fails, virtualization is likely disabled in your BIOS/UEFI firmware. Reboot and enable Intel VT-x or AMD-V.

Dynamips “unable to create VM instance” error

This usually means the IOS image path is wrong or the file permissions are incorrect. Check that your IOS image is readable.

ls -la ~/GNS3/images/IOS/

Make sure Idle-PC is set for each IOS router. Without it, Dynamips consumes 100% CPU per router instance. Right-click the router in GNS3 and select Idle-PC finder.

Server port 3080 already in use

Check what process is using the port.

sudo ss -tlnp | grep 3080

If an old GNS3 server process is stuck, kill it.

pkill -f gns3server

Console connections not working

GNS3 defaults to using xterm for console connections. If xterm is not installed or you prefer another terminal, change it in Edit – Preferences – General – Console Applications. Popular alternatives:

# For GNOME Terminal
gnome-terminal -- telnet %h %p

# For Konsole (KDE)
konsole -e telnet %h %p

# For xfce4-terminal
xfce4-terminal -e "telnet %h %p"

Summary

GNS3 is now installed and running on your Debian 13 or Debian 12 system. You can create network topologies with Dynamips-based Cisco routers, QEMU virtual machines, VPCS nodes, and Docker containers. For larger labs, consider running the GNS3 server on a dedicated machine and connecting to it remotely from the GNS3 GUI client.