How to Fix "externally-managed-environment" Error on macOS During Python Package Installation
When running your ./start.sh script, you encountered the following error:
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try brew install ...
...
See PEP 668 for the detailed specification.
This is a common issue on recent versions of macOS that use the Homebrew-managed Python installation. The Homebrew Python environment is set to prevent global package installs via pip, encouraging safer alternatives.
What Is Happening?
- You’re attempting a system-wide installation with pip (likely for the AWS SDK).
- Homebrew’s Python now blocks system-wide installs to avoid interfering with Homebrew or system packages, enforcing PEP 668 restrictions.
Recommended Solutions
1. Use a Python Virtual Environment (Recommended)
- Avoids system package conflicts and does not require special permissions.
- Steps to set up:
# Create a virtual environment in your project directory
python3 -m venv venv
# Activate the environment
source venv/bin/activate
# Now install your dependencies (e.g., AWS SDK)
pip install awscli boto3
- Your script should be modified or you should always activate the virtual environment before running any install commands.
2. If Only a CLI Tool Is Needed (e.g., awscli)
- Use Homebrew for command-line tools:
brew install awscli
- This is the safest way to install system-wide CLI tools on macOS.
3. Override the Restriction (Not Recommended for Most Users)
You can bypass the restriction with the following command, but this risks breaking your Homebrew Python:
pip install --break-system-packages
or
- Add
break-system-packages = true to your pip.conf.
However, this is discouraged unless you fully understand the risks, as it can corrupt your Homebrew and Python environment.
4. Use pipx for Python Applications
If you're installing Python applications (not libraries):
brew install pipx
pipx install
This will safely manage the application's dependencies in isolated environments.
Why You Should Use a Virtual Environment
- Isolation: Each project gets its own dependencies—no conflicts.
- Portability: Easily recreate the environment elsewhere.
- Safety: No risk of breaking system Python or Homebrew-managed Python.
Table: Installation Options
| Scenario | Recommended Method | Command Example |
|-------------------------|-------------------------------|---------------------------|
| Python Library/SDK | Virtual environment | python3 -m venv venv |
| CLI tool (e.g., awscli) | Homebrew | brew install awscli |
| Python application | pipx | brew install pipx; pipx install ...|
References
- PEP 668 — Marking Python base environments as "externally managed"
- Homebrew Python and pip documentation
- macOS Brew and virtual environment best practices
Summary:
To resolve this, use a Python virtual environment for libraries/development or install CLI tools through Homebrew. This ensures your system remains stable and future-proof.