Because of changes in one of the most popular Python installer on Mac, doc needs an improvement (pip3 install Pygments doesn't work anymore)

[quark67]

On Mac plateform, Python is often installed with the Homebrew package manager (https://en.wikipedia.org/wiki/Homebrew_(package_manager)). But Homebrew is also used on Linux world and the change is not only on HomeBrew.

The change is PEP 668 (https://peps.python.org/pep-0668/).

It was recently implemented in Homebrew, with Python 3.12 (see the very interesting discussion https://github.com/orgs/Homebrew/discussions/3404, titled Python: Mark Homebrew Python as externally managed).

The change is dated from February 21, 2024 (https://github.com/orgs/Homebrew/discussions/3404#discussioncomment-8549228):

@pradyunsg we have now implemented this starting with Python 3.12: Homebrew/homebrew-core#150390, and Python 3.12 has become the default Python 3 in Homebrew so more users will be made aware of the change.

The change is this: pip3 install Pygments doesn't work anymore.

Here is the output:

error: externally-managed-environment

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

If you wish to install a non-brew-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip.

If you wish to install a non-brew packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you. Make sure you have pipx installed.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

Luckily, Pygments is available in Homebrew formulas: https://formulae.brew.sh/formula/pygments#default (but on Mac only for the last 3 majors macOS versions).

So, pip3 install Pygments can be replaced with brew install pygments (for users for which pip3 install doesn't work anymore). Other solution, add --break-system-packages at the end of the command (so use pip3 install Pygments --break-system-packages), see the note at the end of the error message. Also see https://www.youtube.com/watch?v=sFS6rIZN4Lg (problem not only on the Mac).

As on https://github.com/orgs/Homebrew/discussions/3404 some users disagree with the change, perhaps there will be a change which allow further use of pip3 install command without having to use a virtual environment.

I read in the development status of minted that minted 3.0 will not rely on Pygments, but this change with PEP 668 needs to be documented in the final version of minted 2.x, I think.

[muzimuzhi]

I read in the development status of minted that minted 3.0 will not rely on Pygments, ...

In my understanding, minted 3.0 will provide an executable which wraps pygmentize and is compatible with restricted shell escape, so the minted 3.0 still relies on Pygments.

[gpoore]

minted v3.0 is currently available as a beta on GitHub and will have a final release soon. At this point, it looks like all required Python libraries including Pygments will be bundled as part of the LaTeX package, so nothing will need to be installed manually for Python. There will be a new minted2 package for backward compatibility with minted v2, and I will add a note in that part of the documentation about potential installation challenges for Mac.