Skip to main content
Dark‐mode image

PyPI version Downloads Build Status License

Python-BPF is an LLVM IR generator for eBPF programs written in Python. It uses llvmlite to generate LLVM IR and then compiles to LLVM object files. These object files can be loaded into the kernel for execution. Python-BPF performs compilation without relying on BCC.

Note: This project is under active development and not ready for production use.


Overview

  • Generate eBPF programs directly from Python.
  • Compile to LLVM object files for kernel execution.
  • Built with llvmlite for IR generation.
  • Supports maps, helpers, and global definitions for BPF.
  • Companion project: pylibbpf, which provides the bindings required for object loading and execution.

Try It Out!

Run

curl -s https://raw.githubusercontent.com/pythonbpf/Python-BPF/refs/heads/master/tools/setup.sh | sudo bash

Installation

Dependencies:

  • clang
  • Python ≥ 3.8

Install via pip:

pip install pythonbpf pylibbpf

Example Usage

import time
from pythonbpf import bpf, map, section, bpfglobal, BPF
from pythonbpf.helper import pid
from pythonbpf.maps import HashMap
from pylibbpf import *
from ctypes import c_void_p, c_int64, c_uint64, c_int32
import matplotlib.pyplot as plt


# This program attaches an eBPF tracepoint to sys_enter_clone,
# counts per-PID clone syscalls, stores them in a hash map,
# and then plots the distribution as a histogram using matplotlib.
# It provides a quick view of process creation activity over 10 seconds.

@bpf
@map
def hist() -> HashMap:
    return HashMap(key=c_int32, value=c_uint64, max_entries=4096)


@bpf
@section("tracepoint/syscalls/sys_enter_clone")
def hello(ctx: c_void_p) -> c_int64:
    process_id = pid()
    one = 1
    prev = hist.lookup(process_id)
    if prev:
        previous_value = prev + 1
        print(f"count: {previous_value} with {process_id}")
        hist.update(process_id, previous_value)
        return c_int64(0)
    else:
        hist.update(process_id, one)
    return c_int64(0)


@bpf
@bpfglobal
def LICENSE() -> str:
    return "GPL"


b = BPF()
b.load_and_attach()
hist = BpfMap(b, hist)
print("Recording")
time.sleep(10)

counts = list(hist.values())

plt.hist(counts, bins=20)
plt.xlabel("Clone calls per PID")
plt.ylabel("Frequency")
plt.title("Syscall clone counts")
plt.show()

Architecture

Python-BPF provides a complete pipeline to write, compile, and load eBPF programs in Python:

  1. Python Source Code

    • Users write BPF programs in Python using decorators like @bpf, @map, @section, and @bpfglobal.
    • Maps (hash maps), helpers (e.g., ktime, deref), and tracepoints are defined using Python constructs, preserving a syntax close to standard Python.
  2. AST Generation

    • The Python ast module parses the source code into an Abstract Syntax Tree (AST).
    • Decorators and type annotations are captured to determine BPF maps, tracepoints, and global variables.
  3. LLVM IR Emission

    • The AST is transformed into LLVM Intermediate Representation (IR) using llvmlite.
    • IR captures BPF maps, control flow, assignments, and calls to helper functions.
    • Debug information is emitted for easier inspection.
  4. LLVM Object File Compilation

    • The LLVM IR (.ll) is compiled into a BPF target object file (.o) using llc -march=bpf -O2.
    • This produces a kernel-loadable ELF object file containing the BPF bytecode.
  5. libbpf Integration (via pylibbpf)

    • The compiled object file can be loaded into the kernel using pylibbpf.
    • Maps, tracepoints, and program sections are initialized, and helper functions are resolved.
    • Programs are attached to kernel hooks (e.g., syscalls) for execution.
  6. Execution in Kernel

    • The kernel executes the loaded eBPF program.
    • Hash maps, helpers, and global variables behave as defined in the Python source.
    • Output can be read via BPF maps, helper functions, or trace printing.

This architecture eliminates the need for embedding C code in Python, allowing full Python tooling support while generating true BPF object files ready for kernel execution.


Development

  1. Create a virtual environment and activate it:

    python3 -m venv .venv
    source .venv/bin/activate
    
  2. Install dependencies:

    make install
    

    Then, run any example in examples

  3. Verify an object file with the kernel verifier:

    ./tools/check.sh check execve2.o
    
  4. Run an object file using bpftool:

    ./tools/check.sh run execve2.o
    
  5. Explore LLVM IR output from clang in examples/c-form by running make.


Resources


Authors


Metadata

Release files for pythonbpf 0.1.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pythonbpf 0.1.7
File Size Uploaded Provenance Actions
pythonbpf-0.1.7.tar.gz 74.0 kB With provenance Details for pythonbpf-0.1.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pythonbpf 0.1.7
File Interpreter ABI Platform Actions
pythonbpf-0.1.7-py3-none-any.whl Python 3 none any Details for pythonbpf-0.1.7-py3-none-any.whl

Total release size: 162.1 kB

Release files / pythonbpf-0.1.7.tar.gz

Download URL pythonbpf-0.1.7.tar.gz
Size 74.0 kB
Tags Source
SHA-256 checksum
How to use checksums
d82a2f46b1ffc6d31e4484ffba705f374d2ce32e4849d66366deb1be0ca227cd
BLAKE2b-256 checksum
How to use checksums
1afb1663253b049182a2de5e3f1d2047dbe1c6091d98e672677b5cd51e3e443b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2025.

Transparency log

Release files / pythonbpf-0.1.7-py3-none-any.whl

Download URL pythonbpf-0.1.7-py3-none-any.whl
Size 88.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
aaf0278e33993022f3589542c7cf58f64d34bb70ef177bdded2dbe6b33155e49
BLAKE2b-256 checksum
How to use checksums
f1abdf2980ef090716568180898198f2d1f1568d1831cb1ebb1c943d8b262bf4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2025.

Transparency log

Security for pythonbpf 0.1.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pythonbpf-0.1.7.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page