PiAxe – pip3 requirements install break-system-packages

Confirm OS version and Python version. Run `cat /etc/os-release` and record `VERSION_CODENAME` (`bookworm` = PEP 668 active, `bullseye` = not affected). Run `python3 --version` (Bookworm ships `3.11`, next will ship `3.12`) and `pip3 --version`. Run `ls -l /usr/lib/python3.*/EXTERNALLY-MANAGED 2>/dev/null` — if a file is listed, PEP 668 is enforced on that interpreter. This 30-second triage tells you whether this page is your problem (it is, on Bookworm) or whether you should look elsewhere (Bullseye + same error = unusual, possibly a custom pip).

Install python3-venv if missing. `sudo apt install -y python3-venv python3-pip git build-essential python3-dev libffi-dev libssl-dev`. The venv module is sometimes not in the minimal Pi OS Lite image, and the build-essential / dev packages cover the case where `pip install` falls back to compiling C extensions from source on `aarch64`. This single apt line preempts every common Tier-1 install failure.

Create a virtualenv outside the cloned repo. `cd ~ && python3 -m venv piaxe-venv`. Putting the venv at `~/piaxe-venv/` (not inside `~/piaxe-miner/.venv/`) means a future `git clean -fdx` or accidental re-clone of the miner repo can't `rm -rf` your venv. Activate with `source ~/piaxe-venv/bin/activate` — your shell prompt should prefix `(piaxe-venv)`. Inside the venv, `which python` and `which pip` should both point at `~/piaxe-venv/bin/`.

Upgrade pip inside the venv before installing anything. `pip install --upgrade pip`. Pi OS Bookworm's system pip can lag a major version behind upstream; the newer pip handles wheel resolution, dependency conflicts, and `aarch64` / `armv6l` wheel selection more reliably. This costs 15 seconds and prevents an entire class of `Could not find a version that satisfies the requirement` failures.

Install the PiAxe miner requirements inside the venv. `cd ~/piaxe-miner && pip install -r requirements.txt`. With the venv active, this should succeed cleanly — no `externally-managed-environment` error, no `--break-system-packages` flag needed. If it fails on a specific wheel (`bitstring`, `pyyaml`, `cryptography`), the cause is almost always missing build tooling or `gcc`/Python-dev headers — the apt install in Step 2 should have covered this. Confirm `python pyminer.py --help` runs without an `ImportError`.

QUICK PATH (only if you don't want a venv): `pip3 install --break-system-packages -r requirements.txt`. This succeeds in 30 seconds and installs into `/usr/lib/python3.X/dist-packages/`. Use this ONLY on a single-purpose mining Pi that runs nothing else (no pi-hole, no Bitcoin node, no Home Assistant). The pip writes can conflict with future `apt full-upgrade` cycles and break dpkg. The venv path (Steps 3-5) is the right answer 95% of the time.

ORTHODOX PATH (apt-managed deps): for each line in `requirements.txt`, find the matching Debian package: `pyserial` → `python3-serial`, `pyyaml` → `python3-yaml`, `requests` → `python3-requests`, `bitstring` → `python3-bitstring`. `apt-cache search python3-<package>` confirms availability. Run `sudo apt install -y python3-serial python3-yaml python3-requests python3-bitstring`. Test with `python3 -c "import serial, yaml, requests, bitstring"` — silent success means apt has wired everything in. If a dep has no apt package (`bech32` is sometimes missing), fall back to a venv for that one — you can mix paths.

Compile-from-source rescue if a wheel fails to build. On Pi Zero / Pi 1 (`armv6l`), some wheels lack ARM binaries on PyPI and pip compiles from source. Look for `gcc: error` or `Could not build wheels`. Fix: confirm `build-essential python3-dev libffi-dev libssl-dev` are installed (Step 2). On Pi Zero with default 100 MB swap, increase swap before retrying — `sudo nano /etc/dphys-swapfile`, set `CONF_SWAPSIZE=1024`, `sudo /etc/init.d/dphys-swapfile restart`. Compile times on Pi Zero can hit 20 minutes per crypto wheel; be patient.

Wire the venv into systemd. Edit `/etc/systemd/system/pyminer.service` with `sudo nano`. Set `ExecStart=/home/pi/piaxe-venv/bin/python /home/pi/piaxe-miner/pyminer.py`. Set `WorkingDirectory=/home/pi/piaxe-miner`. `User=pi`, `Group=dialout`. `Restart=on-failure`, `RestartSec=10s`. `After=network-online.target systemd-udev-settle.service`, `Wants=network-online.target`. The full path to the venv's Python interpreter is what makes this work — `python3` in the unit's `ExecStart` would use system Python and miss your venv-installed deps.

Reload systemd and start the service. `sudo systemctl daemon-reload && sudo systemctl enable --now pyminer && sudo journalctl -u pyminer -f`. Watch for `BM1366 serial open OK`, `BM1366 chip response OK`, `stratum connecting`, `got new work`. Within 60 seconds the pool dashboard should show non-zero hashrate. If imports still fail (`ModuleNotFoundError`), confirm `ExecStart` is pointing at the venv's Python (`/home/pi/piaxe-venv/bin/python`) and that the venv was activated when you ran `pip install`.

Pin your dependency versions for reproducibility. With the venv active and a working install: `pip freeze > requirements-pinned.txt`. Commit this file to your local repo (or save it on a USB stick). Future `pip install -r requirements-pinned.txt` produces a byte-for-byte identical environment, immune to silent upstream version bumps that occasionally break compatibility with a specific BM1366 firmware revision. Refresh `requirements-pinned.txt` only when you intentionally upgrade.

Build a setup.sh script for fast SD card rebuilds. Drop a 10-line shell script in `~/piaxe-miner/setup.sh` containing the `apt install`, `python3 -m venv`, `source`, `pip install --upgrade pip`, `pip install -r requirements.txt`, and `systemctl enable` commands. `chmod +x setup.sh`. Now rebuilding the SD card from scratch is one command (`./setup.sh`) instead of an afternoon of debugging. This is doubly valuable on multi-PiAxe farms.

Hold critical Python packages against unattended `apt full-upgrade`. `sudo apt-mark hold python3 python3-pip python3-venv`. This prevents an automatic Python minor-version bump (3.11 → 3.12) from invalidating your venv silently — venvs are bound to the exact Python minor they were created against, so a Python upgrade requires recreating the venv. On a long-running mining Pi you don't want surprise venv breakage at 3 AM after auto-update.

Build a multi-Pi golden image. On a freshly-configured Pi (Bookworm, venv set up, `pyminer.service` running cleanly), shut down, pull the SD card, image it with `dd if=/dev/sdX bs=4M of=piaxe-golden-2026MMDD.img status=progress`, compress with `xz`. Flash this image to every other PiAxe SD card you deploy. Each Pi just needs a unique hostname (`sudo raspi-config` → System → Hostname) and re-entered WiFi creds. Saves hours per additional Pi in a farm.

Document and version-control your install recipe. Push `setup.sh`, `requirements-pinned.txt`, and a sanitized copy of `pyminer.service` to a private Git repo. The git history of these three files becomes a working timeline of every change to your PiAxe farm's software stack. When something breaks six months from now, `git blame` tells you exactly when the breakage entered. Treat your mining infrastructure with the same discipline you'd apply to a production server.

Re-image the SD card if dpkg is unrecoverable. After heavy `--break-system-packages` use, you may eventually hit `E: Sub-process /usr/bin/dpkg returned an error code` that resists every `apt --fix-broken install` and `dpkg --configure -a` recovery attempt. At that point, faster path is: shut down, image the BM1366 carrier separately (it stores no state), flash a fresh Pi OS Bookworm image to a new microSD, re-run `setup.sh`. You're back online in 20 minutes instead of debugging dpkg for hours.

Escalate to D-Central pleb-mining queue only if (a) you genuinely killed the BM1366 daughterboard during the adventure (separate failure path), or (b) you want a pre-baked microSD golden image with venv + `pyminer.service` ready to clone for a 10+ unit farm. Email D-Central support with: Pi model, OS version, output of `pip3 --version`, output of `journalctl -u pyminer -n 100`. We don't bench-repair pip installs — but we will ship a pre-configured microSD image at SD-card cost if you're scaling beyond hobby.