Installing on Python 3.12+ / Debian 12+ Systems

Overview

Python 3.12+ on Debian 12, Ubuntu 24.04+, and similar distributions implement PEP 668, which prevents system-wide pip installations to protect system packages. This guide shows how to properly install PCILeechFWGenerator on these systems.

The Problem

When you try to install with pip, you see:

pip install pcileechfwgenerator[tui]
# error: externally-managed-environment

This is expected behavior on modern Linux distributions and is a security feature.

Solution: Use Virtual Environments with sudo

PCILeechFWGenerator requires root privileges for hardware access (VFIO), but also needs Python packages. Here's the correct approach:

Method 1: Virtual Environment (Recommended)

# 1. Create and activate virtual environment
python3 -m venv ~/.pcileech-venv
source ~/.pcileech-venv/bin/activate

# 2. Install PCILeechFWGenerator with all dependencies
pip install pcileechfwgenerator[tui]

# 3. Run with sudo while preserving the venv
# Use the venv's python directly with sudo
sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech tui
# Or if installed with a console script in the venv:
sudo ~/.pcileech-venv/bin/pcileech tui

# OR: Create a helper script
echo '#!/bin/bash' > ~/pcileech
echo 'sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech "$@"' >> ~/pcileech
chmod +x ~/pcileech

# Now you can run:
~/pcileech tui
~/pcileech build --bdf 0000:03:00.0 --board pcileech_35t325_x1

Method 2: Use pipx (System-Wide Tool Installation)

# 1. Install pipx if not already installed
sudo apt install pipx
pipx ensurepath

# 2. Install PCILeechFWGenerator
pipx install pcileechfwgenerator[tui]

# 3. Run with sudo
sudo $(which pcileech) tui

Method 3: System Packages (Override, Not Recommended)

If you absolutely must install system-wide (not recommended):

# Override the externally-managed-environment protection
pip install --break-system-packages pcileechfwgenerator[tui]

# OR: Use the OS package manager approach
# (When/if available as a system package)
sudo apt install python3-pcileechfwgenerator

Running from Source (Development)

For development or running from the repository:

```bash
git clone --recurse-submodules https://github.com/VoltCyclone/PCILeechFWGenerator.git
cd PCILeechFWGenerator

Important: The --recurse-submodules flag is required to initialize the voltcyclone-fpga submodule.

2. Create and activate virtual environment

python3 -m venv .venv source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt pip install -r requirements-tui.txt # For TUI support

4. Run with venv's Python directly

sudo .venv/bin/python3 pcileech.py tui

OR: Use sudo -E (preserves environment)

sudo -E python3 pcileech.py tui

## Understanding sudo + Virtual Environments

### Why `sudo python3` doesn't work with venv

When you run `sudo python3`, it uses the system Python, not your venv's Python, even with `source .venv/bin/activate`. This is because:

1. `sudo` resets the environment by default
2. The `activate` script only modifies shell environment variables
3. `sudo python3` resolves to `/usr/bin/python3`, not `.venv/bin/python3`

### Solutions

#### Option A: Use venv's python directly

```bash
# Explicitly use the venv's Python interpreter
sudo /path/to/.venv/bin/python3 script.py

Option B: Use sudo -E (preserve environment)

# This preserves PATH and other environment variables
sudo -E python3 script.py

Option C: Create wrapper script

#!/bin/bash
# Save as ~/pcileech
sudo /path/to/.venv/bin/python3 /path/to/pcileech.py "$@"

Troubleshooting

"Missing required packages" after installation

Problem: You installed packages but the script still reports them as missing.

Cause: You're running with system Python instead of venv Python.

Solution: Use the venv's Python directly:

sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech tui

"Aborted. Please use a virtual environment"

Problem: The auto-install feature detects you're not in a venv and aborts.

Solution:

1. Install dependencies first: pip install -r requirements.txt requirements-tui.txt
2. Run with venv Python: sudo .venv/bin/python3 pcileech.py tui
3. OR: Set environment variable: export PCILEECH_AUTO_INSTALL=1

pipx installation fails

Problem: pipx install pcileechfwgenerator[tui] fails.

Solution: Install extras separately:

pipx install pcileechfwgenerator
pipx inject pcileechfwgenerator textual rich psutil watchdog pydantic

Best Practices

1. Always use virtual environments for Python projects
2. Never use --break-system-packages unless absolutely necessary
3. Use the venv's Python binary directly when running with sudo
4. Create wrapper scripts for convenience
5. Document your setup for other team members

Quick Reference

# Create venv
python3 -m venv ~/.pcileech-venv

# Install
~/.pcileech-venv/bin/pip install pcileechfwgenerator[tui]

# Run
sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech tui

# Or create alias in ~/.bashrc or ~/.zshrc
alias pcileech='sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech'

See Also