Repository navigation
Installation Guide
Complete installation instructions for all platforms
- Prerequisites
- Installation Methods
- Platform-Specific Instructions
- Verification
- Configuration File Locations
- Troubleshooting
- Upgrading
- Uninstallation
- Next Steps
-
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 (POSIX systems; Windows is not supported natively)
- Memory: Minimum 512MB RAM (1GB+ for production)
- Disk: 50MB for installation
- Network: BGP peer must be reachable
ExaBGP has minimal dependencies - pure Python implementation with no required external libraries.
Installs ExaBGP in an isolated environment with its own Python. Recommended for most users.
pipx install exabgpUpgrade:
pipx upgrade exabgpuv tool install exabgppip install exabgpInstall for current user only (no sudo):
pip install --user exabgpThe binary will be in ~/.local/bin/exabgp: ensure this is in your PATH:
export PATH=$PATH:~/.local/binFor 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.
git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
pip install -e .git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
uv syncgit 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:
- Creating .deb packages → Building From Source
- Creating RPM packages → Building From Source
- Development workflow → Building From Source
git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
./sbin/exabgp --helpgit clone gives you main, the development branch which will become 6.0 (Python 3.12+).
To switch between branches, or to check out a specific release:
git checkout 5.0 # Stable branch (Python 3.8+)
git checkout main # Development branch (future 6.0)
git checkout 5.0.13 # Specific release tag
./sbin/exabgp versionThe healthcheck program can be run from the checkout in any of these ways:
./sbin/exabgp healthcheck --help
env PYTHONPATH=./src python3 -m exabgp healthcheck --help
./bin/healthcheck --helpShould you encounter an issue, we will ask you to install the latest code from git, so it is worth knowing how to do it even if you use a package.
From the source folder, you can create a self-contained executable which only requires an installed python3 interpreter:
git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
./release binary /usr/local/sbin/exabgp
/usr/local/sbin/exabgp version./release binary is a helper which creates a python3 zipapp. The same can be done by
hand:
python3 -m zipapp -o /usr/local/sbin/exabgp -m exabgp.application.main:main -p "/usr/bin/env python3" src
/usr/local/sbin/exabgp versionReleases can also be downloaded from GitHub and run from the extracted folder:
curl -L https://github.com/Exa-Networks/exabgp/archive/5.0.13.tar.gz | tar zx
cd exabgp-5.0.13
./sbin/exabgp version
./sbin/exabgp --helpExaBGP is packaged for many systems, among them Debian, Ubuntu, ArchLinux, Gentoo, FreeBSD and macOS (MacPorts). Many distributions ship an older release, but on the plus side the packaged version is integrated with systemd. Use whichever you prefer, but should you encounter an issue, we will ask you to reproduce it with the latest code from git.
Official Debian/Ubuntu packages:
sudo apt-get update
sudo apt-get install exabgpNote: Distribution packages may be outdated. Use pip for latest version.
Check version:
apt-cache policy exabgpEPEL 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 exabgpAbout 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:
- EPEL 9: https://src.fedoraproject.org/rpms/python-exabgp/tree/epel9
- Fedora Rawhide: https://src.fedoraproject.org/rpms/python-exabgp/tree/rawhide
💡 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 exabgpOr use pip (all versions):
sudo dnf install python3-pip
sudo pip install exabgpAUR package:
yay -S exabgp
# or
paru -S exabgpPorts:
cd /usr/ports/net/exabgp
make install cleanPackages:
pkg install py39-exabgpNote: No official Homebrew formula exists. Use pip:
brew install python3
pip install exabgpOfficial Docker images for containerized deployments via GitHub Container Registry.
# ExaBGP 6.0.0+ (main branch) - Latest development
docker pull ghcr.io/exa-networks/exabgp:latest
# ExaBGP 5.x - Stable
docker pull ghcr.io/exa-networks/exabgp:5.0.13Specific version:
docker pull ghcr.io/exa-networks/exabgp:5.0.13
docker pull ghcr.io/exa-networks/exabgp:5.0 # follows each 5.0 releasedocker 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.confExplanation:
-
-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)
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-stoppedRun:
docker-compose up -dOfficial images are published on GitHub, but you can also build one from the repository:
git clone https://github.com/Exa-Networks/exabgp exabgp-git
cd exabgp-git
docker build -t exabgp ./
docker run -p 179:1790 --mount type=bind,source=`pwd`/etc/exabgp,target=/etc/exabgp -it exabgp -v /etc/exabgp/parse-simple-v4.confYou can add your configuration file to the image and/or use the container like the
exabgp binary. Dockerfile.remote builds an image by installing ExaBGP with pip from
GitHub, and does not need any other file from the repository.
sudo pip install exabgpsudo useradd -r -s /bin/false -c "ExaBGP" exabgpCreate /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.targetEnable and start:
sudo systemctl daemon-reload
sudo systemctl enable exabgp
sudo systemctl start exabgp
sudo systemctl status exabgpbrew install python3pip install exabgpCreate ~/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# Using ports
cd /usr/ports/net/exabgp
make install clean
# Or packages
pkg install py39-exabgppkg_add py3-pip
pip install exabgpCreate /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"
ExaBGP does not run natively on Windows: it imports the POSIX modules fcntl and pwd, which Python on Windows does not provide, and its package declares POSIX and macOS only. On a Windows machine, run it inside a Linux environment, such as WSL, a virtual machine or a Docker container.
exabgp versionExpected output (the first lines):
ExaBGP : 5.0.13
Python : 3.12.3
# or for main branch:
ExaBGP : 6.0.0
which exabgp
# Linux/macOS: /usr/local/bin/exabgp or ~/.local/bin/exabgp
pip show exabgp
# Shows installation location and version# ExaBGP 5.x
exabgp validate /etc/exabgp/exabgp.conf
# ExaBGP 6.x
exabgp configuration validate /etc/exabgp/exabgp.conf
# Check exit code
echo $?
# 0 = valid configuration
# 1 = invalid configuration (error messages printed to stderr)Note: On success the validate command exits with 0, and only prints a few log lines on stderr, such as loading. Errors are printed to stderr.
ExaBGP 4.x: Use exabgp --test /etc/exabgp/exabgp.conf
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/exabgpAfter installation, restart your shell or source the completion file.
ExaBGP includes a production-ready healthcheck module (zero code required!):
exabgp healthcheck --helpYou 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 --no-ip-setupStarted from a terminal, the checker prints the commands it would send to ExaBGP. Without --no-ip-setup it adds 10.0.0.1/32 to the loopback interface, which needs root.
See Healthcheck Module for complete documentation.
env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.confYou should see detailed log output showing ExaBGP starting up.
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
# 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/logError:
-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 python3Error:
-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 --upgradeError:
ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied
Solution 1: Install for current user only
pip install --user exabgpSolution 2: Use sudo (not recommended for production)
sudo pip install exabgpError:
-bash: exabgp: command not found
Solution:
Find where pip installed exabgp:
pip show -f exabgp | grep LocationAdd to PATH:
# For --user installation
export PATH=$PATH:~/.local/bin
# Make permanent
echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
source ~/.bashrcCheck version:
exabgp versionUpgrade:
pip install --upgrade exabgpForce reinstall:
pip install --force-reinstall exabgpError:
ImportError: No module named 'exabgp'
Solution:
Check Python version:
python3 --version # Must be 3.8+ for 5.x, 3.12+ for 6.0.0Reinstall:
pip uninstall exabgp
pip install exabgpVerify installation:
python3 -c "from exabgp.version import version; print(version)"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.confSolution 2: Use systemd/service manager (recommended)
The systemd service above runs as the exabgp user. Adding AmbientCapabilities=CAP_NET_BIND_SERVICE to its [Service] section gives it the 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. When exabgp is a Python script, as pip installs it, Linux ignores a capability set on the script, because capabilities apply to the program executed, here the Python interpreter.
ExaBGP is self-contained and easy to upgrade or downgrade:
- for a release downloaded from GitHub, replace the extracted folder
- for a git checkout, run
git pullin the repository folder - for a pip installation, run
pip install -U exabgp(orpipx upgrade exabgp) - for Debian/Ubuntu, run
apt update; apt upgrade exabgp
Read the CHANGELOG
and check your setup after any upgrade. Moving from 5.0 to main has its own guide:
From 5.x to 6.x.
Several versions can be used at the same time without conflict when ExaBGP is run from
extracted archives, containers and/or local git checkouts. On main, exabgp version
prints the location of the installation which is running, so you can check which one you
are using.
pip uninstall exabgpcd /path/to/exabgp
pip uninstall exabgp# Debian/Ubuntu
sudo apt-get remove exabgp
# FreeBSD
pkg delete exabgpsudo rm -rf /etc/exabgp
sudo rm -rf /var/log/exabgpNow that ExaBGP is installed, continue to:
- Quick Start - Get running in 5 minutes
- Healthcheck Module - ⭐ Production-ready health checks (zero code!)
- First BGP Session - Detailed BGP fundamentals
- Configuration Syntax - Complete configuration reference
- API Overview - Learn the API
- GitHub: https://github.com/Exa-Networks/exabgp
- PyPI: https://pypi.org/project/exabgp/
- Container Registry: https://ghcr.io/exa-networks/exabgp
- Documentation: Home
- Migration Guide: 5.x → 6.0.0 Migration
Installation complete? Continue to Quick Start Guide →
Getting Started
Configuration
- Configuration Syntax
- Neighbor Configuration
- Directives A-Z
- Syntax Reference
- Templates
- Environment Variables
- Process Configuration
API
- API Overview
- Text API Reference
- JSON API Reference
- API Commands
- Writing API Programs
- Error Handling
- Production Best Practices
Address Families
- Overview
- IPv4 Unicast
- IPv6 Unicast
- FlowSpec
- EVPN
- L3VPN
- BGP-LS
- VPLS
- SRv6 / MUP
- Multicast
- RT Constraint
Features
Use Cases
Tools
Operations
Reference
- Architecture
- Design
- Attribute Reference
- Command Reference
- BGP State Machine
- Capabilities
- Communities
- Examples Index
- Glossary
- RFC Support
Integration
Migration
Community
External