한눈에 보기
- 문제: macOS 터미널에서
pip3 install requests를 입력하면error: externally-managed-environment오류가 나면서 설치가 막힙니다. - 원인: Homebrew로 설치한 Python(3.12 이상)은 PEP 668에 따라 “외부에서 관리되는 환경”으로 표시돼 있어서, pip이 가상환경 밖에 설치하는 것을 거부합니다. macOS 버전(Sonoma 등) 때문이 아닙니다.
- 해결:
python3 -m venv venv로 가상환경을 만들고source venv/bin/activate로 켠 뒤pip install requests를 실행합니다. 다음부터는 가상환경을 켜고 스크립트를 실행하면 됩니다.
확인한 환경: macOS, Homebrew Python 3.13, requests 2.32.4 · 처음 쓴 날 2025-07-15 · 마지막 확인 2026-10-28
pip3 install requests에서 나는 externally-managed-environment 오류
macOS에서 Homebrew로 설치한 Python 3로 requests를 쓰는 스크립트를 실행하려고 아래처럼 pip3 install requests를 입력하면, 경고문이 잔뜩 뜨면서 설치가 되지 않습니다.
user % pip3 install requests
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 Python library that isn't in Homebrew,
use a virtual environment:
python3 -m venv path/to/venv
source path/to/venv/bin/activate
python3 -m pip install xyz
If you wish to install a Python application that isn't in Homebrew,
it may be easiest to use 'pipx install xyz', which will manage a
virtual environment for you. You can install pipx with
brew install pipx
You may restore the old behavior of pip by passing
the '--break-system-packages' flag to pip, or by adding
'break-system-packages = true' to your pip.conf file. The latter
will permanently disable this error.
If you disable this error, we STRONGLY recommend that you additionally
pass the '--user' flag to pip, or set 'user = true' in your pip.conf
file. Failure to do this can result in a broken Homebrew installation.
Read more about this behavior here: <https://peps.python.org/pep-0668/>
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.원인: Homebrew Python과 PEP 668
이 오류는 Homebrew가 자기가 설치한 Python에 “외부에서 관리되는 환경(externally managed)”이라는 표시를 해 두었기 때문에 납니다. 이 표시는 Python 표준 라이브러리 폴더에 들어 있는 EXTERNALLY-MANAGED라는 파일입니다. PEP 668에 정해진 규칙에 따라, pip은 가상환경 밖에서 이 파일을 발견하면 Homebrew가 관리하는 패키지를 덮어쓰지 않도록 설치를 멈춥니다. 쉽게 말해, Homebrew Python 본체에는 pip으로 직접 설치하지 말라는 뜻입니다.
그래서 이 오류는 macOS 버전(Sonoma 이상 등)과는 상관이 없습니다. 어떤 Python을 쓰느냐에 따라 달라집니다. Homebrew는 Python 3.12부터 이 규칙을 따르고 있고, 아래 설치 기록의 파일 이름(cp313)을 보면 이 글을 쓸 때의 환경은 Homebrew Python 3.13이었습니다. 반대로 macOS에 딸려 오는 /usr/bin/python3(Command Line Tools의 Python 3.9)에는 이 표시 파일이 없어서 같은 오류가 나지 않습니다.
2026년 10월 기준으로도 Homebrew 공식 문서는 자기 Python을 PEP 668에 따라 “외부에서 관리되는 환경”으로 표시한다고 밝히고 있습니다. 그리고 프로젝트에 필요한 패키지는 Homebrew Python 본체가 아니라 가상환경에 설치하라고 안내합니다(Homebrew 문서: Language Runtimes and Packages).
해결: 가상환경(venv)에 requests 설치하기
모든 경고를 무시하고 과감하게 설치하는 방법도 있지만, 나중에 무슨 일이 생길지 모르니 권장하는 방법대로 안전하게 해 보겠습니다.
가장 안전하고 권장되는 방법은 가상환경(venv)에 설치하는 것입니다. 조금 귀찮기는 하지만 잘 작동합니다.
python3 -m venv venv
source venv/bin/activate
pip install requests이렇게 python3로 venv 가상환경을 만들고, 그 가상환경을 켠(activate) 다음 requests를 설치하면 아무 일 없었다는 듯이 자연스럽게 설치됩니다.
....
Collecting requests
Using cached requests-2.32.4-py3-none-any.whl.metadata (4.9 kB)
Collecting charset_normalizer<4,>=2 (from requests)
Using cached charset_normalizer-3.4.2-cp313-cp313-macosx_10_13_universal2.whl.metadata (35 kB)
Collecting idna<4,>=2.5 (from requests)
Using cached idna-3.10-py3-none-any.whl.metadata (10 kB)
Collecting urllib3<3,>=1.21.1 (from requests)
Using cached urllib3-2.5.0-py3-none-any.whl.metadata (6.5 kB)
Collecting certifi>=2017.4.17 (from requests)
Using cached certifi-2025.7.14-py3-none-any.whl.metadata (2.4 kB)
Using cached requests-2.32.4-py3-none-any.whl (64 kB)
Using cached charset_normalizer-3.4.2-cp313-cp313-macosx_10_13_universal2.whl (199 kB)
Using cached idna-3.10-py3-none-any.whl (70 kB)
Using cached urllib3-2.5.0-py3-none-any.whl (129 kB)
Using cached certifi-2025.7.14-py3-none-any.whl (162 kB)
Installing collected packages: urllib3, idna, charset_normalizer, certifi, requests
Successfully installed certifi-2025.7.14 charset_normalizer-3.4.2 idna-3.10 requests-2.32.4 urllib3-2.5.0설치한 뒤에는 프롬프트 앞에 가상환경을 나타내는 (venv)가 표시됩니다.
venv 환경에 requests를 설치했으니, 앞으로 venv를 켜면 그 환경에 설치된 라이브러리가 잘 작동합니다.
터미널을 다시 열었을 때 가상환경 켜기
터미널을 다시 연 뒤에는 가상환경을 만든 폴더에서 아래처럼 venv 환경을 다시 켜고 사용하면 됩니다.
user@iMac iMacEXT % source venv/bin/activate
(venv) user@iMac iMacEXT % python3 python_script.py
다른 방법: pipx와 –break-system-packages는 언제 쓰나
오류 메시지에는 가상환경 말고도 몇 가지 방법이 나옵니다. 공식 문서를 기준으로 언제 쓰는지 정리하면 이렇습니다.
- 가상환경(venv): requests처럼 스크립트나 프로젝트에서 불러 쓰는 라이브러리를 설치할 때 씁니다. 이 글에서 쓴 방법이고, Homebrew 문서와 PEP 668이 기본으로 권하는 방법입니다.
- pipx: 명령줄에서 실행하는 Python 프로그램(앱)을 설치할 때 씁니다.
brew install pipx로 설치한 뒤pipx install 앱이름을 실행하면, 앱마다 가상환경을 따로 만들어 줍니다. requests는 코드에서 불러 쓰는 라이브러리라서 pipx가 아니라 venv에 설치합니다. --break-system-packages: 표시를 무시하고 Homebrew Python 본체에 강제로 설치하는 옵션입니다. Python 패키징 공식 사양은 이 옵션을 위험한 선택지로 두고, 오류 메시지도 쓰려면--user를 함께 쓰라고 하면서 그러지 않으면 Homebrew 설치가 망가질 수 있다고 경고합니다. 다른 방법이 정말 없을 때만 씁니다.
자주 묻는 질문
macOS에서 pip3 install을 하면 왜 externally-managed-environment 오류가 나나요?
Homebrew로 설치한 Python(3.12 이상)이 PEP 668에 따라 “외부에서 관리되는 환경”으로 표시돼 있기 때문입니다. pip은 가상환경 밖에서 이 표시를 보면 설치를 멈춥니다. macOS 버전 문제가 아니라 어떤 Python을 쓰느냐의 문제입니다.
–break-system-packages를 붙여서 설치해도 되나요?
설치는 되지만 권하지 않습니다. Homebrew가 관리하는 패키지를 pip이 덮어써서 Homebrew Python이 망가질 수 있습니다. 스크립트에서 쓸 라이브러리라면 가상환경(venv)에 설치하는 편이 안전합니다.
터미널을 다시 열 때마다 가상환경을 켜야 하나요?
네, 가상환경을 만든 폴더에서 source venv/bin/activate를 다시 실행합니다. 켜지 않고 venv/bin/python python_script.py처럼 가상환경 안의 Python을 바로 불러도 됩니다. 다 쓴 뒤에는 deactivate를 입력하면 가상환경이 꺼집니다(Python 공식 문서: venv).
pipx로 requests를 설치하면 안 되나요?
pipx는 명령줄에서 실행하는 Python 앱을 앱마다 따로 가상환경에 설치하는 도구입니다. requests는 스크립트에서 불러 쓰는 라이브러리라서, 그 스크립트가 쓰는 가상환경(venv)에 설치해야 합니다.
함께 보면 좋은 글
- GitHub 문서를 NotebookLM에서 활용하는 방법 — GitHub 저장소의 문서를 NotebookLM에 불러와 질문하며 읽는 방법입니다.
- Cloudflare SSL/TLS 설정 (ERR_TOO_MANY_REDIRECTS 해결) — Cloudflare SSL/TLS 모드 때문에 생기는 무한 리디렉션 오류를 고치는 방법입니다.
답글 남기기