Skip to content

Installation on Python 3.12+ / Debian 12+

The Problem

Starting with Python 3.12 and Debian 12 (Bookworm), system Python packages are protected by PEP 668's "externally managed environment" feature. Running pip install directly will fail with:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

The Solution: Virtual Environment

The recommended approach is to use a virtual environment:

# Create a dedicated virtual environment
python3 -m venv ~/.pcileech-venv

# Activate it
source ~/.pcileech-venv/bin/activate

# Install with TUI support
pip install pcileechfwgenerator[tui]

# Verify installation
pcileech version

Running with sudo

Since PCILeech requires root access for VFIO operations, you need to run the venv's Python directly with sudo:

# DON'T do this (won't find the package):
sudo pcileech tui

# DO this instead (use the venv's Python directly):
sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech_main tui

# Or create an alias in ~/.bashrc:
alias pcileech-sudo='sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech_main'

# Then use:
pcileech-sudo tui
pcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1

Alternative: pipx

You can also use pipx which automatically manages virtual environments:

# Install pipx
sudo apt install pipx
pipx ensurepath

# Install pcileechfwgenerator
pipx install 'pcileechfwgenerator[tui]'

# Run (still needs sudo for VFIO)
sudo $(which pcileech) tui

If you understand the risks, you can override the protection:

# NOT RECOMMENDED - can break system packages
pip install --break-system-packages pcileechfwgenerator[tui]

This is discouraged because it can cause conflicts with system Python packages managed by apt.

Troubleshooting

"ModuleNotFoundError: No module named 'textual'"

The TUI dependencies weren't installed. Make sure you installed with [tui]:

pip install pcileechfwgenerator[tui]

"command not found: pcileech"

The virtual environment isn't activated, or you're using sudo which doesn't inherit PATH:

# Either activate the venv first:
source ~/.pcileech-venv/bin/activate
pcileech version

# Or use the full path with the venv's Python:
sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech_main tui

# Or use the alias (after adding to ~/.bashrc):
pcileech-sudo tui

"Permission denied" errors during build

You need root access for VFIO operations. Use the venv's Python with sudo:

sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech_main build --bdf 0000:03:00.0 --board pcileech_35t325_x1

Quick Reference

# One-time setup
python3 -m venv ~/.pcileech-venv
source ~/.pcileech-venv/bin/activate
pip install pcileechfwgenerator[tui]

# Daily usage (add to ~/.bashrc for convenience)
alias pcileech-sudo='sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech_main'

# Run commands
pcileech-sudo tui
pcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1
pcileech-sudo check --device 0000:03:00.0