errors · 3.2pip, with Homebrew's Python on macOS

error: externally-managed-environment

You ran pip install fasm (or pip install -e . inside prjxray) with Homebrew's Python and pip refused with a long message that starts with this line and mentions PEP 668.

Why does it happen?

Homebrew marks its Python as externally managed, which means pip is not allowed to install into it and break packages that Homebrew itself relies on. Two steps of the FPGA chain are Python scripts (bbaexport.py for the chip database and fasm2frames for the bitstream) and they need a handful of packages.

What is the fix?

Make a venv, a private Python where you are free to install things, and use it for every Python command in the chain. The guide keeps it next to everything else in ~/fpga.

mkdir -p ~/fpga
"$(brew --prefix)/opt/python@3.14/bin/python3.14" -m venv ~/fpga/venv
~/fpga/venv/bin/pip install fasm==0.0.2.post88 pyyaml==6.0.3 textx==4.4.0 simplejson==4.1.2 intervaltree==3.2.1 numpy==2.5.3 pyjson5==2.0.1

Later, prjxray is installed into the same venv with ~/fpga/venv/bin/pip install --no-deps -e ., and the Makefile calls ~/fpga/venv/bin/python instead of python3.

Do not use --break-system-packages. It does what it says.

Section 3.2 of the guide: Python venv.