From 018fb82f441af2fe3914d9dcdc64ad0da79409f6 Mon Sep 17 00:00:00 2001 From: Lee Rhodes Date: Sat, 10 Oct 2026 14:54:42 -0700 Subject: [PATCH] README: explain the externally-managed-environment error Homebrew Python and recent Debian and Ubuntu system Pythons refuse pip installs into the base environment (PEP 668). Say what the error means and how to install into a virtual environment instead, without making a virtual environment part of the general instructions. Fixes #46. Co-Authored-By: Claude Opus 5.5 --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index 99614966..ee25a7c5 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,14 @@ If you prefer to call the `setup.py` build script directly, which is discouraged The library is also available from PyPI via `python3 -m pip install datasketches`. +If either command fails with `error: externally-managed-environment`, your Python installation (for example, Homebrew Python or the system Python on recent Debian and Ubuntu releases) does not allow installing packages into it directly ([PEP 668](https://peps.python.org/pep-0668/)). Install into a virtual environment instead: + +``` +python3 -m venv .venv +source .venv/bin/activate +python3 -m pip install datasketches # or: python3 -m pip install . +``` + ## Usage Having installed the library, loading the Apache DataSketches Library in Python is simple: `import datasketches`.