gregclermont · gregclermont · Jan 21, 2026 · Jan 19, 2026 · Jan 19, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -106,6 +106,29 @@ jobs:
           name: wheel-${{ matrix.arch }}
           path: dist/*.whl
 
+  build-sdist:
+    needs: prepare
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist
+        run: |
+          pip install build
+          python -m build --sdist
+
+      - name: Upload sdist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
   test-wheel-x86_64:
     needs: [build, build-ebpf]
     uses: ./.github/workflows/_test-wheel.yml
@@ -123,7 +146,7 @@ jobs:
       wheel-artifact: wheel-aarch64
 
   release:
-    needs: [prepare, build, test-wheel-x86_64, test-wheel-aarch64]
+    needs: [prepare, build, build-sdist, test-wheel-x86_64, test-wheel-aarch64]
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -132,10 +155,16 @@ jobs:
       - name: Download all wheel artifacts
         uses: actions/download-artifact@v4
         with:
-          path: wheels
+          path: dist
           pattern: wheel-*
           merge-multiple: true
 
+      - name: Download sdist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
       - name: Create release
         uses: softprops/action-gh-release@v2
         with:
@@ -155,7 +184,9 @@ jobs:
             # index-url = "https://gregclermont.github.io/tinybpf/"
             # ///
             ```
-          files: wheels/*.whl
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
 
   update-index:
     needs: [prepare, release]
@@ -184,9 +215,9 @@ jobs:
           <body>
           HTMLEOF
 
-          # Fetch all wheel URLs from releases and add to index
+          # Fetch all wheel and sdist URLs from releases and add to index
           gh release list --json tagName --jq '.[].tagName' | grep '^v' | while read tag; do
-            gh release view "$tag" --json assets --jq '.assets[].url' | grep '\.whl$' | while read url; do
+            gh release view "$tag" --json assets --jq '.assets[].url' | grep -E '\.(whl|tar\.gz)$' | while read url; do
               filename=$(basename "$url")
               echo "<a href=\"$url\">$filename</a>" >> tinybpf/index.html
             done

diff --git a/README.md b/README.md
@@ -25,6 +25,33 @@ pip install tinybpf --extra-index-url https://gregclermont.github.io/tinybpf
 
 Wheels available for `manylinux_2_28_x86_64` and `manylinux_2_28_aarch64`.
 
+<details>
+<summary>Using system libbpf</summary>
+
+To use your system's libbpf instead of the bundled version:
+
+```bash
+# Install system libbpf
+apt install libbpf-dev  # Debian/Ubuntu
+dnf install libbpf-devel  # Fedora/RHEL
+
+# Install from source distribution (no bundled libbpf)
+uv add tinybpf --index https://gregclermont.github.io/tinybpf --no-binary tinybpf
+# or: pip install --no-binary tinybpf tinybpf --extra-index-url https://gregclermont.github.io/tinybpf
+```
+
+Then initialize with the system library path before using tinybpf:
+
+```python
+import tinybpf
+
+tinybpf.init("/usr/lib/x86_64-linux-gnu/libbpf.so.1")  # Debian/Ubuntu
+# tinybpf.init("/usr/lib64/libbpf.so.1")  # Fedora/RHEL
+```
+
+Requires libbpf 1.0+.
+</details>
+
 ## Usage
 
 ```python

diff --git a/llms.txt b/llms.txt
@@ -9,7 +9,7 @@ uv add tinybpf --index https://gregclermont.github.io/tinybpf
 pip install tinybpf --extra-index-url https://gregclermont.github.io/tinybpf
 ```
 
-Requires Linux 5.8+ (for ring buffers; basic features work on older kernels), libelf, root/CAP_BPF. Wheels: manylinux_2_28 x86_64/aarch64.
+Requires Linux 5.8+ (for ring buffers; basic features work on older kernels), libelf, root/CAP_BPF. Wheels: manylinux_2_28 x86_64/aarch64. Source distribution also available for use with system libbpf (1.0+): `uv add --no-binary tinybpf` or `pip install --no-binary tinybpf`, then `tinybpf.init("/usr/lib/.../libbpf.so.1")`.
 
 ## Detailed Docs
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -77,3 +77,6 @@ known-first-party = ["tinybpf"]
 [tool.ruff.format]
 quote-style = "double"
 indent-style = "space"
+
+[tool.uv]
+environments = ["sys_platform == 'linux'", "sys_platform == 'darwin'"]
diff --git a/src/tinybpf/_libbpf/bindings.py b/src/tinybpf/_libbpf/bindings.py
@@ -6,6 +6,7 @@
 import ctypes.util
 import fcntl
 import os
+import sys
 import threading
 from contextlib import contextmanager, suppress
 from pathlib import Path
@@ -362,6 +363,13 @@ def init(libbpf_path: str | Path | None = None) -> None:
 
 def _load_bundled() -> ctypes.CDLL:
     """Load bundled libbpf.so from package directory."""
+    if sys.platform != "linux":
+        raise OSError(
+            f"tinybpf requires Linux (current platform: {sys.platform}). "
+            "The package can be imported on other platforms for type checking, "
+            "but BPF operations require a Linux system."
+        )
+
     pkg_dir = Path(__file__).parent
     for name in ["libbpf.so.1", "libbpf.so"]:
         path = pkg_dir / name
@@ -370,7 +378,10 @@ def _load_bundled() -> ctypes.CDLL:
 
     raise OSError(
         "Bundled libbpf.so not found. "
-        "Use a wheel with bundled library or call init(libbpf_path='...')."
+        "If you installed from source, use system libbpf:\n"
+        "  1. Install: apt install libbpf-dev  # or equivalent\n"
+        "  2. Initialize: tinybpf.init('/usr/lib/x86_64-linux-gnu/libbpf.so.1')\n"
+        "Or install a wheel: pip install --only-binary :all: tinybpf"
     )