Installation

This guide will walk you through installing PythonBPF and its dependencies.

Prerequisites

System Requirements

PythonBPF requires:

Linux - eBPF is a Linux kernel feature (kernel 4.15 or higher recommended)
Python 3.10+ - Python 3.10 or higher is required
Root/sudo access - Loading BPF programs into the kernel requires elevated privileges

Required System Packages

Before installing PythonBPF, you need to install the following system packages:

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y bpftool clang llvm

On Fedora/RHEL/CentOS:

sudo dnf install -y bpftool clang llvm

On Arch Linux:

sudo pacman -S bpf clang llvm

Installing PythonBPF

From PyPI (Recommended)

The easiest way to install PythonBPF is using uv or pip:

Using uv (recommended):

uv pip install pythonbpf pylibbpf

Using pip:

pip install pythonbpf pylibbpf

This will install:

pythonbpf - The main package for writing and compiling BPF programs
pylibbpf - Python bindings for libbpf, used to load and attach BPF programs

Development Installation

If you want to contribute to PythonBPF or work with the latest development version:

Clone the repository:

git clone https://github.com/pythonbpf/Python-BPF.git
cd Python-BPF

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install in development mode:

Using uv (recommended):

uv pip install -e .
uv pip install pylibbpf

Using pip:

pip install -e .
pip install pylibbpf

Install development dependencies:

make install

Installing Documentation Dependencies

If you want to build the documentation locally:

Using uv (recommended):

uv pip install pythonbpf[docs]
# Or from the repository root:
uv pip install -e .[docs]

Using pip:

pip install pythonbpf[docs]
# Or from the repository root:
pip install -e .[docs]

Generating vmlinux.py

vmlinux.py contains the running kernel’s data structures and is analogous to vmlinux.h included in eBPF programs written in C. Some examples require access to it. To use these features, you need to generate a vmlinux.py file:

Install additional dependencies:

Using uv (recommended):

uv pip install ctypeslib2

Using pip:

pip install ctypeslib2

Generate the vmlinux.py file:

sudo tools/vmlinux-gen.py

Copy the generated file to your working directory or the examples directory as needed.

Warning

The vmlinux.py file is kernel-specific. If you upgrade your kernel, you may need to regenerate this file.

Verifying Installation

To verify that PythonBPF is installed correctly, run:

python3 -c "import pythonbpf; print(pythonbpf.__all__)"

You should see output similar to:

['bpf', 'map', 'section', 'bpfglobal', 'struct', 'compile_to_ir', 'compile', 'BPF', 'trace_pipe', 'trace_fields']

Troubleshooting

Permission Errors

If you encounter permission errors when running BPF programs:

Make sure you’re running with sudo or as root
Check that /sys/kernel/tracing/ is accessible

LLVM/Clang Not Found

If you get errors about llc or clang not being found:

Verify they’re installed: which llc and which clang
Check your PATH environment variable includes the LLVM bin directory

Import Errors

If Python can’t find the pythonbpf module:

Make sure you’ve activated your virtual environment
Verify installation with uv pip list | grep pythonbpf or pip list | grep pythonbpf
Try reinstalling: uv pip install --force-reinstall pythonbpf or pip install --force-reinstall pythonbpf

Next Steps

Now that you have PythonBPF installed, continue to the Quick Start guide to write your first BPF program!