python-bpf/docs/getting-started/installation.md

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

The `llvm` package provides `llc`, the LLVM compiler that is used to compile LLVM IR to BPF bytecode.

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:

1. Clone the repository:

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

2. Create and activate a virtual environment:

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

3. Install in development mode:

Using uv (recommended):

uv pip install -e .
uv pip install pylibbpf

Using pip:

pip install -e .
pip install pylibbpf

4. 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

Some examples require access to kernel data structures. To use these features, you need to generate a vmlinux.py file:

1. Install additional dependencies:

Using uv (recommended):

uv pip install ctypeslib2

Using pip:

pip install ctypeslib2

2. Generate the vmlinux.py file:

sudo tools/vmlinux-gen.py

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

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 {doc}quickstart guide to write your first BPF program!