Skip to content

docs(readme): recommend pipx for install (fixes PEP 668 + global dep conflicts)#1237

Open
OmkarKirpan wants to merge 1 commit intoMemPalace:developfrom
OmkarKirpan:fix/readme-pipx-install
Open

docs(readme): recommend pipx for install (fixes PEP 668 + global dep conflicts)#1237
OmkarKirpan wants to merge 1 commit intoMemPalace:developfrom
OmkarKirpan:fix/readme-pipx-install

Conversation

@OmkarKirpan
Copy link
Copy Markdown

@OmkarKirpan OmkarKirpan commented Apr 27, 2026

Summary

The pip install mempalace line in the README either fails on
PEP 668-managed Pythons (Debian/Ubuntu, Homebrew) or silently upgrades
chromadb / numpy / grpcio / click in the user's global
site-packages and breaks unrelated tools.

A real run on macOS today, against a Python that already had numba,
litellm, tutor, and the OpenTelemetry instrumentation packages
installed, produced this from a single pip install mempalace:

opentelemetry-instrumentation 0.62b0 requires
  opentelemetry-semantic-conventions==0.62b0, but you have 0.62b1
numba 0.61.2 requires numpy<2.3,>=1.24, but you have numpy 2.4.4
litellm 1.80.11 requires grpcio<1.68.0,>=1.62.3, but you have grpcio 1.80.0
tutor 20.0.2 requires click<8.3.0,>=8.0, but you have click 8.3.3

mempalace ships a CLI, so pipx install mempalace (or
uv tool install mempalace) is the right default — it isolates the
install and still puts mempalace on PATH. Plain pip install is
kept as the documented alternative for users who want import mempalace inside their own activated venv.

Refs #284 (PEP 668 / --break-system-packages).

What changed

  • README.md "Install" section: lead with pipx install mempalace,
    mention uv tool install as an equivalent, briefly explain why
    (PEP 668 + global dep conflicts), and keep pip install for the
    in-venv case.
  • No code changes.

Test plan

  • git diff README.md — only the Install section changes
  • pipx install mempalace succeeds on a system Python where
    pip install mempalace would either trip PEP 668 or
    downgrade/upgrade global packages

…flicts

The current 'pip install mempalace' instruction either fails outright
on PEP 668-managed Pythons (Debian/Ubuntu, Homebrew) or upgrades
chromadb / numpy / grpcio / click in the user's global site-packages
and breaks unrelated tools (numba, litellm, tutor, opentelemetry, ...).

mempalace ships a CLI, so pipx (or 'uv tool install') is the right
default — it isolates the install and still puts 'mempalace' on PATH.
Plain pip is kept as the alternative for users who want 'import
mempalace' inside their own venv.

Refs MemPalace#284
@OmkarKirpan OmkarKirpan force-pushed the fix/readme-pipx-install branch from 23ff292 to afa0c31 Compare April 27, 2026 15:02
@igorls
Copy link
Copy Markdown
Member

igorls commented Apr 27, 2026

Looks good and it's the way it should be installed indeed. @bensig @milla-jovovich ok on this ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants