Homebrew installations of python throw an error on building

Open

#46 opened on Apr 5, 2024 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty: 1/5
Estimated time: Under an hour
Newbie friendliness: 55/100

Issue type: Documentation
Clarity: Clearly specified
Activity status: Stale
Tech stack: python
Domain: documentation

Research direction

Start with the README's build and installation section and reproduce the Homebrew Python installation error if needed. Add the proposed virtual-environment commands, then run tox to verify the documented setup works.

Written by the indexing model from the issue text.

Description

When building with a homebrew installation of python an error is raised. We can avoid this by installing in a virtual environment as suggested by the error message. For example

>> which python3
>> /opt/homebrew/bin/python3

>> python3 -m pip install .
>> 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.

It is easy to resolve this by doing (in an appropriate directory, eg. assume the following is in project root).
I propose to add the following notes to the build and installation part of the readme.

python3 -m venv venv
source venv/bin/activate
python3 -m pip install .
python3 -m pip install tox
tox

Dominant language: Jupyter Notebook
Stars: 46
Forks: 9
PR merge metrics: No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.

Similar issues

Update DEPENDENCIES.md for the TypeScript implementation Open

Difficulty 2/5 1-3 hours Newbie friendliness 78/100

agilepathway/label-checker#640 · Opened Sep 22, 2026
[Bounty proposal] docs(cli): Sorani (ckb) agent quickstart ($25 proposed) Open

Difficulty 2/5 1-3 hours Newbie friendliness 75/100

BasedHardware/omi#15662 · 1 comment · Opened Sep 22, 2026
Document that a SQLite trail allows only one writer Open

documentation help wanted

Difficulty 2/5 1-3 hours Newbie friendliness 90/100

rajfirke/provena#202 · Opened Sep 22, 2026
Docs are out of date: README structure tree, "Make It Yours" pointer, CONTRIBUTING test notes Open

documentation good first issue

Difficulty 2/5 1-3 hours Newbie friendliness 88/100

amponce/archive-movie-browser#167 · Opened Sep 22, 2026
Gateway 3.16 Linux install: GPG key URL 404s (public_keys has no "316" entry, falls back to legacy key) Open

user-reported

Difficulty 2/5 1-3 hours Newbie friendliness 85/100

Kong/developer.konghq.com#7316 · Opened Sep 22, 2026