Skip to content

Installation Guide

Jump to bottom
Thomas Mangin edited this page Mar 6, 2026 · 10 revisions

Installation Guide

Complete installation instructions for all platforms

Table of Contents

Prerequisites

System Requirements

  • Python:
    • ExaBGP 6.0.0+ (main): Python 3.12 or later (3.13, 3.14 tested)
    • ExaBGP 5.x: Python 3.8 or later (3.9+ recommended, 3.13 tested)
    • ExaBGP 4.x: Python 3.6 or later (also supports Python 2.7, deprecated)
    • ⚠️ Python 2 completely removed in ExaBGP 5.0.0
    • ⚠️ Python 3.7-3.11 dropped in ExaBGP 6.0.0
  • OS: Linux, macOS, *BSD, Windows
  • Memory: Minimum 512MB RAM (1GB+ for production)
  • Disk: 50MB for installation
  • Network: BGP peer must be reachable

Python Packages (automatically installed)

ExaBGP has minimal dependencies - pure Python implementation with no required external libraries.

Installation Methods

pipx (Recommended)

Installs ExaBGP in an isolated environment with its own Python. Recommended for most users.

pipx install exabgp

Upgrade:

pipx upgrade exabgp

uv (Fast, Modern)

uv tool install exabgp

pip

pip install exabgp

Install for current user only (no sudo):

pip install --user exabgp

The binary will be in ~/.local/bin/exabgp — ensure this is in your PATH:

export PATH=$PATH:~/.local/bin

From Source

For development, testing, or running the latest unreleased features.

📚 Comprehensive Guide: See Building From Source for complete instructions on building ExaBGP from source, creating Debian/RPM packages, and development workflow.

Quick Start — Clone and Install

git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
pip install -e .

Development with uv (recommended)

git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
uv sync

Install Specific Branch

git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
git checkout 5.0  # Or any branch/tag
pip install -e .

For more advanced options:

Run Without Installing

git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
./sbin/exabgp --help

Package Managers

Debian/Ubuntu

Official Debian/Ubuntu packages:

sudo apt-get update
sudo apt-get install exabgp

Note: Distribution packages may be outdated. Use pip for latest version.

Check version:

apt-cache policy exabgp

Red Hat/CentOS/Fedora

EPEL 9 repository (RHEL 9, Fedora 36+):

💡 Attribution: EPEL packaging guidance provided by @garybuhrmaster in Issue #1166.

A recent version of ExaBGP 4.2.21+ is available in EPEL 9 (Enterprise Linux 9):

# Enable EPEL repository
sudo dnf install epel-release

# Install from EPEL (currently in updates-testing)
sudo dnf --refresh --enablerepo=epel-testing install exabgp

# Once stable, will be available as:
# sudo dnf install exabgp

About EPEL packaging:

Quote from Gary Buhrmaster: "The packaging has been modified from the generic spec file on this site to use (what the RH python packagers call) 'modern' python build macros available in Fedora and EL9, along with various other RH distro specific adjustments (all distros have slight differences in packaging preferences)."

The SPEC file and packaging details are available in Fedora dist-git:

💡 Maintainer Note: The Fedora ExaBGP packager (Gary Buhrmaster) intends to keep the EPEL9 version in sync with the latest ExaBGP releases until/unless dependencies cannot be met.

Legacy RHEL/CentOS (using yum):

# Enable EPEL
sudo yum install epel-release

# Install ExaBGP
sudo yum install exabgp

# If not available in EPEL, use pip
sudo yum install python3-pip
sudo pip install exabgp

Or use pip (all versions):

sudo dnf install python3-pip
sudo pip install exabgp

Arch Linux

AUR package:

yay -S exabgp
# or
paru -S exabgp

FreeBSD

Ports:

cd /usr/ports/net/exabgp
make install clean

Packages:

pkg install py39-exabgp

macOS (Homebrew)

Note: No official Homebrew formula exists. Use pip:

brew install python3
pip install exabgp

Docker

Official Docker images for containerized deployments via GitHub Container Registry.

Pull Image

# ExaBGP 6.0.0+ (main branch) - Latest development
docker pull ghcr.io/exa-networks/exabgp:latest

# ExaBGP 5.x - Stable LTS
docker pull ghcr.io/exa-networks/exabgp:5.0.0

Specific version:

docker pull ghcr.io/exa-networks/exabgp:5.0.0
docker pull ghcr.io/exa-networks/exabgp:4.2.25

Run Container

docker run -it --rm \
  -v /path/to/exabgp.conf:/etc/exabgp/exabgp.conf:ro \
  -v /path/to/api-scripts:/etc/exabgp/api:ro \
  --network host \
  ghcr.io/exa-networks/exabgp:latest \
  exabgp /etc/exabgp/exabgp.conf

Explanation:

  • -v /path/to/exabgp.conf:/etc/exabgp/exabgp.conf:ro - Mount config (read-only)
  • -v /path/to/api-scripts:/etc/exabgp/api:ro - Mount API scripts
  • --network host - Use host networking for BGP (TCP 179)

Docker Compose

Create docker-compose.yml:

version: '3'
services:
  exabgp:
    image: ghcr.io/exa-networks/exabgp:latest
    container_name: exabgp
    network_mode: host
    volumes:
      - ./exabgp.conf:/etc/exabgp/exabgp.conf:ro
      - ./api:/etc/exabgp/api:ro
    command: exabgp /etc/exabgp/exabgp.conf
    restart: unless-stopped

Run:

docker-compose up -d

Platform-Specific Instructions

Linux

System-wide Installation

sudo pip install exabgp

Create System User (recommended for production)

sudo useradd -r -s /bin/false -c "ExaBGP" exabgp

Systemd Service

Create /etc/systemd/system/exabgp.service:

[Unit]
Description=ExaBGP BGP Speaker
After=network.target

[Service]
Type=simple
User=exabgp
Group=exabgp
ExecStart=/usr/local/bin/exabgp /etc/exabgp/exabgp.conf
ExecReload=/bin/kill -USR1 $MAINPID
Restart=on-failure
RestartSec=5

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/run/exabgp

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable exabgp
sudo systemctl start exabgp
sudo systemctl status exabgp

macOS

Install Python 3

brew install python3

Install ExaBGP

pip install exabgp

launchd Service

Create ~/Library/LaunchAgents/com.exabgp.daemon.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.exabgp.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/exabgp</string>
        <string>/usr/local/etc/exabgp/exabgp.conf</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/exabgp.log</string>
    <key>StandardOutPath</key>
    <string>/usr/local/var/log/exabgp.log</string>
</dict>
</plist>

Load service:

launchctl load ~/Library/LaunchAgents/com.exabgp.daemon.plist

BSD

FreeBSD

# Using ports
cd /usr/ports/net/exabgp
make install clean

# Or packages
pkg install py39-exabgp

OpenBSD

pkg_add py3-pip
pip install exabgp

rc.d Service (FreeBSD/OpenBSD)

Create /etc/rc.d/exabgp:

#!/bin/sh
#
# PROVIDE: exabgp
# REQUIRE: NETWORKING
# KEYWORD: shutdown

. /etc/rc.subr

name="exabgp"
rcvar=exabgp_enable
command="/usr/local/bin/exabgp"
command_args="/usr/local/etc/exabgp/exabgp.conf"
pidfile="/var/run/${name}.pid"

load_rc_config $name
run_rc_command "$1"

Enable in /etc/rc.conf:

exabgp_enable="YES"

Windows

Install Python 3

Download and install Python from https://www.python.org/downloads/

Important: Check "Add Python to PATH" during installation.

Install ExaBGP

pip install exabgp

Run ExaBGP

exabgp C:\exabgp\exabgp.conf

Windows Service (NSSM)

Use NSSM (Non-Sucking Service Manager) to run ExaBGP as a service:

  1. Download NSSM: https://nssm.cc/download
  2. Install service:
nssm install ExaBGP "C:\Python39\Scripts\exabgp.exe" "C:\exabgp\exabgp.conf"
nssm start ExaBGP

Verification

Check Version

exabgp version

Expected output:

ExaBGP 5.0.0
# or for main branch:
ExaBGP 6.0.0

Check Installation Path

which exabgp
# Linux/macOS: /usr/local/bin/exabgp or ~/.local/bin/exabgp

pip show exabgp
# Shows installation location and version

Test Configuration Syntax

# ExaBGP 5.x and 6.x
exabgp configuration validate /etc/exabgp/exabgp.conf

# Check exit code
echo $?
# 0 = valid configuration (no output)
# 1 = invalid configuration (error messages printed)

Note: The validate command produces no output on success, only sets exit code to 0. Errors are printed to stderr.

ExaBGP 4.x: Use exabgp configuration validate /etc/exabgp/exabgp.conf

Install Shell Completion (ExaBGP 6.0.0+)

ExaBGP 6.0.0 includes dynamic shell completion for Bash, Zsh, and Fish:

# Auto-detect shell and install
exabgp shell install

# Or specify shell explicitly
exabgp shell install bash
exabgp shell install zsh
exabgp shell install fish

# Manual installation
exabgp shell completion bash > ~/.local/share/bash-completion/completions/exabgp

After installation, restart your shell or source the completion file.

Test Built-in Healthcheck Module

ExaBGP includes a production-ready healthcheck module (zero code required!):

exabgp healthcheck --help

You should see available options for health checks, IP management, metrics, and execution hooks.

Example health check test:

# Test a simple health check command
exabgp healthcheck --cmd "curl -sf http://localhost" --ip 10.0.0.1/32 --interval 5

See Healthcheck Module for complete documentation.

Run in Debug Mode

env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.conf

You should see detailed log output showing ExaBGP starting up.

Configuration File Locations

Standard Locations

Linux:

  • /etc/exabgp/exabgp.conf - Main configuration
  • /etc/exabgp/api/ - API scripts
  • /var/log/exabgp.log - Log file

macOS:

  • /usr/local/etc/exabgp/exabgp.conf
  • /usr/local/var/log/exabgp.log

FreeBSD:

  • /usr/local/etc/exabgp/exabgp.conf
  • /var/log/exabgp.log

Create Directories

# Linux
sudo mkdir -p /etc/exabgp/api
sudo mkdir -p /var/log/exabgp
sudo chown -R exabgp:exabgp /etc/exabgp /var/log/exabgp

# macOS
sudo mkdir -p /usr/local/etc/exabgp/api
sudo mkdir -p /usr/local/var/log

Troubleshooting

Python 3 Not Found

Error:

-bash: python3: command not found

Solution:

# Debian/Ubuntu
sudo apt-get install python3 python3-pip

# Red Hat/CentOS
sudo yum install python3 python3-pip

# macOS
brew install python3

pip Not Found

Error:

-bash: pip3: command not found

Solution:

# Debian/Ubuntu
sudo apt-get install python3-pip

# Red Hat/CentOS
sudo yum install python3-pip

# Using Python
python3 -m ensurepip --upgrade

Permission Denied

Error:

ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied

Solution 1: Install for current user only

pip install --user exabgp

Solution 2: Use sudo (not recommended for production)

sudo pip install exabgp

ExaBGP Not in PATH

Error:

-bash: exabgp: command not found

Solution:

Find where pip installed exabgp:

pip show -f exabgp | grep Location

Add to PATH:

# For --user installation
export PATH=$PATH:~/.local/bin

# Make permanent
echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
source ~/.bashrc

Old Version Installed

Check version:

exabgp version

Upgrade:

pip install --upgrade exabgp

Force reinstall:

pip install --force-reinstall exabgp

ImportError or Missing Modules

Error:

ImportError: No module named 'exabgp'

Solution:

Check Python version:

python3 --version  # Must be 3.8+ for 5.x, 3.12+ for 6.0.0

Reinstall:

pip uninstall exabgp
pip install exabgp

Verify installation:

python3 -c "import exabgp; print(exabgp.__version__)"

BGP Port 179 Permission Denied

Error:

Permission denied: Could not bind to port 179

Explanation: Port 179 requires root/administrator privileges.

Solution 1: Run ExaBGP as root (not recommended)

sudo exabgp /etc/exabgp/exabgp.conf

Solution 2: Use systemd/service manager (recommended)

The systemd service runs as exabgp user but has capability to bind to port 179.

Solution 3: Use port > 1024

Configure your BGP peer to connect to ExaBGP on a high port instead of 179. Not all routers support this.

Solution 4: Grant capability (Linux)

sudo setcap 'cap_net_bind_service=+ep' $(which exabgp)

This allows exabgp binary to bind to privileged ports without running as root.

Uninstallation

pip Installation

pip uninstall exabgp

Source Installation

cd /path/to/exabgp
pip uninstall exabgp

Package Manager

# Debian/Ubuntu
sudo apt-get remove exabgp

# FreeBSD
pkg delete exabgp

Remove Configuration

sudo rm -rf /etc/exabgp
sudo rm -rf /var/log/exabgp

Next Steps

Now that ExaBGP is installed, continue to:

Additional Resources

Installation complete? Continue to Quick Start Guide →

Home

Getting Started

Configuration

API

Address Families

Features

Use Cases

Tools

Operations

Reference

Integration

Migration

Community

External

Clone this wiki locally