pip externally-managed-environment, Debian 13에서 venv·uv로 설치
Debian 13 서버에서 pip로 패키지 하나를 넣으려다 externally-managed-environment에 막히면, 배포 작업은 그 자리에서 멈춥니다. 이때 먼저 가려야 할 것은 패키지가 문제인지, 설치하려는 위치가 문제인지입니다. 운영 서버의 Python 패키지 설치 절차를 정하는 데 필요한 것은 시스템 설치가 막히는 조건과 프로젝트 가상환경으로 풀리는지였고, 둘 다 같은 서버에서 명령을 실행해 비교했습니다. 설치 명령이 성공했는지만큼이나, 서비스가 실제로 어떤 Python으로 뜨는지도 봐야 합니다. 대상은 같은 httpx 하나로 고정하고, 시스템 pip와 venv·uv의 결과를 비교한 뒤 import까지 이어지는지 따라갔습니다.
시험한 Debian 13 서버와 대상 패키지
| 항목 | 확인 내용 |
|---|---|
| OS | Debian GNU/Linux 13 (trixie) |
| Python | 3.13.5 |
| pip | 25.1.1 — /usr/lib/python3/dist-packages/pip |
| uv | 0.13.0 |
| 설치 대상 | httpx — 가상환경에서 0.28.1 확인 |
| 확인일 | 2026-10-15 KST |
대상 패키지는 시스템 Python에 깔려 있지 않은 httpx입니다. 시스템 설치를 먼저 시도하고, 같은 패키지를 프로젝트 가상환경에 넣어 결과를 견줍니다. 패키지 이름은 그대로 두고 설치 대상 환경만 바꾸니, 차이가 생긴다면 그 원인은 환경 쪽에 있다고 봅니다. 운영 서버에 적용할 때도 설치 명령 한 줄만 적지 말고 Python과 pip의 버전, 설치 위치를 같이 남기기를 권장합니다.
성공 여부는 두 가지로 판단합니다. 설치 명령의 종료 코드, 그리고 그 가상환경 Python에서 import가 되는지입니다. 시스템 Python에서 패키지가 보이는지도 따로 봅니다. 결국 이번 문제는 설치 단계와 실행 단계를 같은 환경에 맞추는 것으로 풀립니다.
pip가 시스템 Python 설치를 거부할 때
같은 명령으로 오류 다시 만들기
재현은 운영체제와 도구 버전을 찍고, 배포판의 관리 표시 파일이 있는지 보는 데서 시작합니다. 그다음 시스템 Python에 연결된 pip로 설치를 시도합니다. 재현 스크립트의 핵심 명령은 이렇습니다.
. /etc/os-release; echo "$PRETTY_NAME"; python3 --version; python3 -m pip --version
ls -l /usr/lib/python3.13/EXTERNALLY-MANAGED
python3 -m pip install httpx; echo "pip_exit=$?"출력에서 Python은 3.13.5, 시스템 pip는 25.1.1이고, pip 위치는 배포판이 관리하는 경로로 나옵니다. EXTERNALLY-MANAGED 파일을 확인한 뒤의 설치 시도는 externally-managed-environment와 pip_exit=1을 남겼습니다. 오류 안내 자체가 가상환경을 만들라고 제시하고 있으니, 같은 명령을 다시 두드리기보다 설치할 환경을 떼어 내는 쪽으로 갑니다.
$ . /etc/os-release; echo "$PRETTY_NAME"; python3 --version; python3 -m pip --version
Debian GNU/Linux 13 (trixie)
Python 3.13.5
pip 25.1.1 from /usr/lib/python3/dist-packages/pip (python 3.13)
$ ls -l /usr/lib/python3.13/EXTERNALLY-MANAGED
-rw-r--r-- 1 root root 645 Aug 10 21:06 /usr/lib/python3.13/EXTERNALLY-MANAGED
$ python3 -m pip install httpx; echo "pip_exit=$?"
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.
If you wish to install a non-Debian-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. Make
sure you have python3-full installed.
If you wish to install a non-Debian 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.
See /usr/share/doc/python3.13/README.venv for more information.
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.
pip_exit=1
관리 정책에 걸려 설치가 멈춘 터미널입니다. pip_exit=1과 오류 이름을 같이 기록해 두면, 자동 배포 로그에서 같은 실패를 만났을 때 한눈에 알아보기 쉽습니다. 안내문이 시스템 패키지 관리와 가상환경이라는 두 갈래를 보여 주므로, 프로젝트 의존성을 어느 쪽에 둘지 정하는 출발점으로 읽으면 됩니다.
배포판이 관리하는 Python 환경이라는 원인
pip_exit=1과 externally-managed-environment가 함께 나타납니다. 이 서버에는 /usr/lib/python3.13/EXTERNALLY-MANAGED 파일이 있으며, pip는 시스템 환경에 대한 설치를 거부합니다. PEP 668 (확인일 2026-10-15)의 환경 관리 경계와 연결되는 동작입니다. 그러니 이번 오류에서는 설치 대상이 배포판 관리 영역인지부터 판단합니다.
에러 안내는 시스템 전체에 필요한 패키지라면 apt install python3-xyz 형태를 살펴보고, 프로젝트 패키지에는 가상환경을 사용하도록 안내합니다. 여기서 xyz는 설치할 패키지를 나타내는 자리입니다. Debian의 Python 관리 기준은 Debian Python 정책 (확인일 2026-10-15)을 함께 참고합니다. 아래에서는 실제 설치와 import 결과가 있는 가상환경 경로를 따라 해결합니다.
프로젝트 가상환경으로 옮겨 설치하기
프로젝트 작업 디렉터리에서 .venv를 생성하고, 그 안의 pip로 httpx를 설치합니다. 설치 후에도 같은 디렉터리의 Python으로 import를 수행합니다. Python venv 문서 (확인일 2026-10-15)를 참고할 수 있으며, 이번 절차에서는 실행 파일 경로를 명시해 설치와 실행의 대상을 맞춥니다.
python3 -m venv .venv
.venv/bin/pip install -q httpx
.venv/bin/python -c "import httpx, sys; print("httpx", httpx.__version__); print("prefix", sys.prefix)"
python3 -c "import sys; print("system prefix", sys.prefix)"해결 스크립트는 가상환경 생성, 패키지 설치, import, 시스템 prefix 확인을 차례로 밟습니다. 출력의 venv_exit=0과 pip_exit=0은 생성과 설치가 각각 통과했다는 뜻입니다. 뒤이어 나온 httpx 0.28.1과 prefix를 같이 보면, 패키지를 어느 환경에서 불러왔는지까지 이어서 확인됩니다. prefix에는 작업 디렉터리 이름이 그대로 찍히므로, 운영에 옮길 때는 자기 프로젝트 경로로 실행 설정을 바꿔 써야 합니다.
$ python3 -m venv .venv && echo "venv_exit=$?"
venv_exit=0
$ .venv/bin/pip install -q httpx; echo "pip_exit=$?"
pip_exit=0
$ .venv/bin/python -c "import httpx, sys; print(\"httpx\", httpx.__version__); print(\"prefix\", sys.prefix)"
httpx 0.28.1
prefix /home/user/pip-pep668/.venv
$ python3 -c "import sys; print(\"system prefix\", sys.prefix)"
system prefix /usr
가상환경 생성과 패키지 설치 모두 종료 값 0입니다. import 결과는 httpx 0.28.1이고, 프로젝트 prefix와 시스템의 /usr가 분명히 갈립니다. 이 화면과 실행 환경을 운영 기록에 같이 붙여 두면, 인수인계 때 설치 위치를 다시 뒤지는 수고가 줄어듭니다.
캡처의 prefix 값은 실제 작업 폴더 아래 .venv를 가리키고, 본문에서는 이를 /home/user/pip-pep668/.venv로 옮겨 적었습니다.
venv_exit=0과 pip_exit=0을 확인하고, 가상환경 Python에서 httpx 0.28.1을 출력합니다. 가상환경 prefix는 ~/pip-pep668/.venv이며 시스템 prefix는 /usr로 출력됩니다. 설치가 끝난 뒤에도 프로젝트 실행 명령에 .venv/bin/python을 사용하도록 정리합니다.
venv 방식은 Python의 venv 생성 명령과 환경 내부 pip 경로만으로 설치 대상과 실행 대상을 분명히 가르고, 이번 실행에서도 생성과 설치, import 결과가 한 출력에 같이 남았습니다. 그 대신 프로젝트를 실행할 때마다 가상환경 Python 경로를 맞춰야 합니다. 설치에는 .venv/bin/pip를 쓰고 실행에는 시스템 python3를 쓰는 식으로 섞이지 않게 관리합니다.
uv를 쓰는 서버라면 설치 대상 Python을 지정합니다
uv를 사용하는 서버에서는 .uvenv를 만들고 --python .uvenv/bin/python으로 설치 대상을 명시합니다. uv 환경 문서 (확인일 2026-10-15)를 참고하면서, 여기서는 서버에 있는 uv 0.13.0으로 실행합니다. 설치 도구가 바뀌어도 프로젝트 환경에 패키지를 넣고 그 환경의 Python으로 실행한다는 원칙을 유지합니다.
uv --version
uv venv -q .uvenv && uv pip install -q --python .uvenv/bin/python httpx
.uvenv/bin/python -c "import httpx; print("httpx", httpx.__version__)"
python3 -c "import httpx"점검 스크립트 출력에는 uv로 풀기 전에 시도한 --user 설치 결과도 들어 있습니다. 사용자 설치는 pip_user_exit=1로 끝났고, uv 설치는 uv_exit=0으로 완료됐습니다. 설치 대상을 바꾸자 결과가 뒤집힌 셈입니다. 마지막에는 시스템 Python에서 같은 패키지를 import해 환경 차이를 확인합니다. 여기서 나온 ModuleNotFoundError: No module named 'httpx'는 실패라기보다, 앞의 가상환경 설치가 시스템과 분리되어 있다는 증거로 읽어야 합니다.
$ python3 -m pip install --user httpx 2>&1 | head -2; echo "pip_user_exit=${PIPESTATUS[0]}"
error: externally-managed-environment
pip_user_exit=1
$ uv --version
uv 0.13.0 (x86_64-unknown-linux-gnu)
$ uv venv -q .uvenv && uv pip install -q --python .uvenv/bin/python httpx; echo "uv_exit=$?"
uv_exit=0
$ .uvenv/bin/python -c "import httpx; print(\"httpx\", httpx.__version__)"
httpx 0.28.1
$ python3 -c "import httpx" 2>&1 | tail -1
ModuleNotFoundError: No module named 'httpx'
한 실행 기록 안에서 사용자 설치 실패와 uv 가상환경 설치 성공이 나란히 보입니다. --user를 붙여도 관리 환경 오류는 그대로였고, 대상 Python을 지정한 uv 설치 뒤에는 httpx 0.28.1이 불러와졌습니다. 마지막의 시스템 Python import 실패까지 이어 보면, 실행 명령에도 가상환경 경로를 적어야 하는 이유가 분명해집니다.
uv_exit=0과 가상환경의 httpx 0.28.1 출력을 확인합니다. 마지막 시스템 Python 명령은 ModuleNotFoundError를 출력합니다. 이 비교에서 가상환경에는 설치된 패키지가 시스템 Python에서는 보이지 않는다는 점을 확인합니다. 서비스 실행 설정에도 이 구분을 반영해야 설치 작업의 성공이 실제 프로세스의 실행으로 이어집니다.
uv 방식은 --python 옵션에 대상 환경 경로를 적어 설치 위치를 못 박고, 이어서 같은 환경의 Python으로 import 결과를 봅니다. 다만 uv 도구와 가상환경 경로를 함께 관리해야 하니, 기존에 venv만 쓰던 작업 절차라면 uv 버전 확인과 대상 지정 명령을 운영 문서에 더해 둡니다.
–user 설치와, 설치는 됐는데 import가 실패하는 경우
–user를 붙여도 막히는가
사용자 영역으로 설치하면 해결될 것이라 예상하기 쉽지만, 이번 서버에서는 python3 -m pip install --user httpx도 같은 오류로 종료합니다. 점검 스크립트 출력의 pip_user_exit=1이 그 결과입니다. 그래서 이 서버에서는 --user를 해결 절차로 반복하지 않고 프로젝트 가상환경으로 전환합니다. 시스템 설치와 사용자 설치를 비교할 때는 옵션 차이뿐 아니라 실제 종료 코드도 함께 읽습니다.
설치는 됐는데 import가 실패할 때
설치는 됐는데 import가 안 된다면, 패키지를 다시 깔기 전에 실행한 Python 경로부터 대조하십시오. 이번 uv 결과에서도 .uvenv/bin/python의 import는 성공했고 python3의 import는 실패했습니다. 운영 작업에서도 설치 명령과 실행 명령을 나란히 놓고 같은 가상환경을 가리키는지 확인하면, 이번 출력처럼 환경이 섞인 경우를 금방 가려낼 수 있습니다.
버전 충돌을 점검할 때도 시스템 pip 버전과 가상환경 패키지 버전을 한 항목처럼 취급하지 않도록 합니다. 이번 기록에서 pip 25.1.1은 시스템 경로에서 확인한 버전이며, httpx 0.28.1은 각각의 가상환경에서 import해 확인한 버전입니다. 가상환경 내부 pip 버전까지 같은 값이라고 추정하지 않고, 출력에 드러난 도구와 경로를 기준으로 기록합니다.
가상환경을 따라 맞추는 Python 실행 경로
이 기록을 읽을 때 놓치기 쉬운 점은 도구 버전과 설치 환경이 짝을 이룬다는 사실입니다. 출력에는 시스템 pip와 uv의 버전, 가상환경에서 불러온 패키지 버전이 따로따로 나옵니다. 운영체제나 Python을 올릴 때 예전 설치 명령을 그대로 다시 쓰기 전에, 관리 표시 파일과 실행 파일 경로가 지금 환경에 맞는지부터 봅니다. 오류 안내에 나오는 문서 경로도 배포판에 설치된 Python 버전에 맞춰 운영 문서에서 고쳐 두는 편이 좋습니다.
서비스 설정과 헬스체크의 기준도 패키지를 설치한 가상환경이어야 합니다. 애플리케이션은 가상환경으로 돌리면서 점검 명령만 시스템 Python을 부르면, 이번 출력처럼 import가 실패해 멀쩡한 설치를 고장으로 오판하게 됩니다. Kubernetes에서 Python을 부르는 probe를 쓴다면 서비스와 같은 가상환경 경로를 지정하고, 환경을 다시 만들거나 배포 위치를 옮길 때 실행 설정과 점검 설정을 한꺼번에 고칩니다. 웹 응답으로 점검하더라도, 배포 단계에서 같은 Python의 import를 먼저 확인해 두면 의존성 문제를 좁히기 쉽습니다.
에러 안내의 선택지 가운데 피해야 할 옵션
가상환경 생성 전 필요한 환경을 점검할 때는 에러 안내의 python3-full 설치 안내와 /usr/share/doc/python3.13/README.venv 경로를 참고합니다. 이번 venv 생성은 성공했으므로 본문에서는 성공한 명령과 결과를 중심으로 절차를 정리합니다. pipx는 애플리케이션 단위 설치용으로 에러 안내에 나오는 선택지로 구분합니다.
--break-system-packages는 에러 안내에 나오기는 하지만, 운영 서버의 해결 명령으로는 권하지 않습니다. apt가 관리하는 파일과 부딪쳐 시스템 도구를 망가뜨릴 위험이 있기 때문입니다. 기본 운영 절차로는 이번 실행에서 설치에 성공한 venv와 uv 경로를 추천합니다. 운영 문서에도 이 위험 옵션을 기본 설치 명령에 붙이지 말고, 프로젝트 환경 경로를 명시해 두십시오.
설치와 실행이 같은 환경을 가리키는지가 해결 기준
| 방식 | 이번 실행 결과 또는 안내 | 선택 기준 |
|---|---|---|
| 시스템 pip install | externally-managed-environment, pip_exit=1 | 배포판 관리 환경인지 먼저 확인합니다. |
| pip install –user | 같은 오류, pip_user_exit=1 | 이번 서버의 해결책으로 사용하지 않습니다. |
| venv + 환경 내부 pip | 설치 성공, httpx 0.28.1 import 성공 | Python venv 중심의 프로젝트에 추천합니다. |
| uv + 대상 Python 지정 | 설치 성공, httpx 0.28.1 import 성공 | uv를 사용하는 프로젝트에 추천합니다. |
| –break-system-packages | 에러 안내에 위험을 동반한 옵션으로 등장 | 시스템 도구 손상 위험 때문에 권하지 않습니다. |
상황별로 보면 고르는 기준은 현재 운영 절차입니다. Python venv로 프로젝트 환경을 관리한다면 .venv/bin/pip와 .venv/bin/python을 짝지어 쓰는 흐름이 맞습니다. uv를 쓰는 서버라면 uv venv로 환경을 만들고 uv pip install --python으로 대상을 지정합니다. 시스템 전체의 패키지 관리가 목적이라면 에러 안내의 apt 선택지를 살펴보도록 합니다.
출력을 비교해 보면 분명해지는 것은, 설치 도구가 무엇이냐보다 설치와 실행이 같은 환경을 가리키느냐가 이 문제의 해결 기준이라는 점입니다. 저라면 기존 Python 프로젝트에는 venv 구성을 먼저 적용하고, 이미 uv를 쓰는 프로젝트에는 대상 Python을 명시하는 구성을 권하겠습니다. 배포 절차에는 환경 생성과 설치의 종료 코드뿐 아니라, 그 환경에서의 import 확인도 넣습니다. 실시간 서비스라면 시작 명령과 헬스체크가 같은 의존성을 읽도록 배포 설정을 한데 묶어 관리합니다. 작업자 터미널에서 설치가 성공했다는 사실이 곧 서비스 프로세스가 준비됐다는 뜻은 아니기 때문입니다. 운영 문서에는 프로젝트 경로와 실행 파일을 함께 적어, 다음 배포에서도 같은 환경을 다시 꾸릴 수 있게 합니다.
