데비안 리눅스에서 파이썬 확장 모듈을 설치하기 위한 pip가 없거나, pip 설치 후에도 This environment is externally managed 오류가 발생하는 경우가 있다. 이 글에서는 데비안의 파이썬 패키지 관리 정책이 변경된 이유와, 시스템 Python을 건드리지 않고 venv 가상 환경을 통해 파이썬 확장 모듈을 안전하게 설치하고 사용하는 방법을 실제 콘솔 예제를 기반으로 정리한다.
파이썬(Python) 확장 모듈과 pip의 역할
파이썬은 윈도우와 리눅스를 가리지 않고 폭넓게 활용되는 프로그래밍 언어이다. 방대한 확장 모듈 생태계를 바탕으로, 복잡한 기능을 비교적 짧은 코드로 구현할 수 있다는 점이 큰 장점이다. 유튜브 API 연동과 같은 실사용 목적의 파이썬 프로그램 대부분은 하나 이상의 확장 모듈에 의존하며, 이를 설치하고 관리하는 과정이 필수적으로 요구된다. 이러한 확장 모듈의 설치와 관리를 담당하는 도구가 바로 pip이다.
데비안 리눅스에서 pip 설치 방법
기본 데비안 리눅스 환경에는 pip가 포함되지 않는다
기본적인 절차에 따라 데비안 리눅스를 설치했다면, 파이썬 인터프리터 자체는 기본 설치되어 있지만, 확장 모듈 관리 도구인 pip는 설치되지 않은 것을 확인할 수 있다.
eqmaker@debian:~$ python3 Python 3.11.2 (main, Apr 28 2025, 14:11:48) [GCC 12.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> exit() eqmaker@debian:~$ python3 -m pip install google-api-python-client /usr/bin/python3: No module named pip
때문에, 확장 모듈을 사용하는 실사용 목적의 파이썬 프로그램을 실행하기 위해서는 우선 pip를 설치하는 과정이 필요하다.
데비안 리눅스의 파이썬 pip 설치 절차
데비안 리눅스에서 pip는 apt를 통해 간단히 설치할 수 있다. 우선 apt update를 통해 저장소를 업데이트 해 주고, apt install python3-pip -y명령을 실행해 pip를 설치해 준다.
eqmaker@debian:~$ sudo apt update [sudo] password for eqmaker: Hit:1 http://deb.debian.org/debian trixie InRelease ... (중략) ... All packages are up to date. eqmaker@debian:~$ sudo apt install python3-pip -y Installing: python3-pip Installing dependencies: binutils gcc libcrypt-dev libjs-sphinxdoc make ... (중략) ... g++-x86-64-linux-gnu libcc1-0 libjs-jquery linux-libc-dev Suggested packages: binutils-doc debian-keyring autoconf gcc-doc libc-devtools ed ... (중략) ... cpp-14-doc gcc-multilib gdb | httpd make-doc Summary: Upgrading: 0, Installing: 67, Removing: 0, Not Upgrading: 0 Download size: 93.0 MB Space needed: 361 MB / 212 GB available Get:1 http://deb.debian.org/debian trixie/main amd64 libsframe1 amd64 2.44-3 [78.4 kB] Get:2 http://deb.debian.org/debian trixie/main amd64 binutils-common amd64 2.44-3 [2,509 kB] ... (중략) ... Get:65 http://deb.debian.org/debian trixie/main amd64 python3-wheel all 0.46.1-2 [21.7 kB] Get:66 http://deb.debian.org/debian trixie/main amd64 python3-pip all 25.1.1+dfsg-1 [1,457 kB] Get:67 http://deb.debian.org/debian trixie/main amd64 sq amd64 1.3.1-2+b1 [5,654 kB] Fetched 93.0 MB in 8s (11.0 MB/s) Extracting templates from packages: 100% Selecting previously unselected package libsframe1:amd64. (Reading database ... 29348 files and directories currently installed.) Preparing to unpack .../00-libsframe1_2.44-3_amd64.deb ... Unpacking libsframe1:amd64 (2.44-3) ... ... (중략) ... Setting up build-essential (12.12) ... Processing triggers for man-db (2.13.1-1) ... Processing triggers for libc-bin (2.41-12) ... eqmaker@debian:~$
데비안 리눅스 pip 설치 후 발생하는 externally managed 에러
pip 설치를 완료한 뒤 다시 파이썬 확장 모듈 설치를 시도하면, 이번에는 No module named pip 대신, This environment is externally managed라는 에러 메시지가 출력되는 것을 확인할 수 있다.
eqmaker@debian:~$ python3 -m pip install google-api-python-client
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. ...(이하 생략)
This environment is externally managed 에러의 의미와 원인
This environment is externally managed라는 메시지는 데비안의 패키지 관리 체계와 파이썬의 패키지(모듈) 관리 체계의 충돌을 방지하기 위한 경고이다.
데비안 리눅스의 달라진 파이썬 모듈 관리 방식
과거에는 pip install 명령을 통해 시스템 전역에 파이썬 확장 모듈을 직접 설치하는 것이 가능했다. 문제는, 데비안 리눅스와 Python은 apt를 통해 설치·업데이트되는 패키지들과 의존성 관계를 공유한다는 것이다.
apt는 배포판 기준으로 검증된 파이썬 패키지를 관리하는 반면, pip는 PyPI 생태계 전반의 모듈을 개별 프로젝트 단위로 관리한다. 때문에 두 도구가 동일한 Python 경로를 수정할 경우, 파이썬 모듈과 데비안 배포판 패키지가 충돌하거나 오동작 하는 경우가 생겨나기 시작했다.
이를 방지하기 위해 데비안은 버전 12(북웜, Bookworm) 이후로 Python을 externally managed environment로 지정했다. 이후의 데비안 리눅스 시스템은 Python 환경을 외부에서 관리되는 환경으로 지정하고, pip의 직접적인 개입을 제한하고 있다.
externally managed 환경에서 venv가 필요한 이유
이 문제를 해결하기 위해 등장한 것이 파이썬의 가상 환경 기능인 venv이다. venv는 데비안 시스템의 Python과 완전히 분리된 독립적인 실행 환경을 제공하며, 이 환경 안에서는 pip를 이용한 확장 모듈 설치가 자유롭게 가능하다. 즉, 시스템을 건드리지 않으면서도 필요한 파이썬 모듈을 안전하게 사용할 수 있는 방법이다.
결론적으로, 데비안 리눅스 환경에서 파이썬 확장 모듈을 사용하려면, 시스템 Python을 직접 수정하는 대신 venv 기반의 가상 환경을 구성해 주어야 한다.
데비안 리눅스에서 파이썬 venv로 확장 모듈 설치하기
venv는 데비안 시스템이 관리하는 파이썬 환경과 완전히 분리된 독립적인 실행 공간을 제공하며, 각 가상 환경은 자체적인 모듈 설치 경로를 가진다. 이로 인해 venv 내부에서는 pip를 이용한 확장 모듈 설치를 마음대로 할 수 있다.
데비안 리눅스 파이썬 venv 설치 방법
우선, apt를 이용해 python3-venv 패키지를 설치한다.
eqmaker@debian:~$ sudo apt install python3-venv -y Installing: python3-venv Installing dependencies: python3-pip-whl python3-setuptools-whl python3.13-venv Summary: Upgrading: 0, Installing: 4, Removing: 0, Not Upgrading: 0 Download size: 2,782 kB Space needed: 2,957 kB / 212 GB available Get:1 http://deb.debian.org/debian trixie/main amd64 python3-pip-whl all 25.1.1+dfsg-1 [1,507 kB] Get:2 http://deb.debian.org/debian trixie/main amd64 python3-setuptools- ... (중략) ... Setting up python3-pip-whl (25.1.1+dfsg-1) ... Setting up python3.13-venv (3.13.5-2) ... Setting up python3-venv (3.13.5-1) ... eqmaker@debian:~$
Step 1. venv 가상 환경 생성
가상 환경을 생성할 디렉토리로 이동하여 아래와 같이 가상 환경을 생성한다.
eqmaker@debian:~$ python3 -m venv ~/venv eqmaker@debian:~$ ls -l total 4 drwxrwxr-x 5 eqmaker eqmaker 4096 Dec 19 11:18 venv eqmaker@debian:~$
본 필자는 home 디렉토리에 venv라는 이름으로 가상 환경을 생성했다. ls명령을 통해 가상 환경에 사용할 디렉토리가 생성된 것이 확인된다.
Step 2. venv 가상 환경 활성화
source 명령을 이용해 아래와 같이 가상 환경을 활성화 시켜 준다. 프롬프트가 변경되며 파이썬 가상환경 모드에 진입한 것이 표시된다.
eqmaker@debian:~$ source ~/venv/bin/activate (venv) eqmaker@debian:~$
Step 3. venv 환경에서 확장 모듈 설치
가상 환경이 활성화된 상태에서는 pip를 이용한 확장 모듈 설치가 정상적으로 동작한다.
(venv) eqmaker@debian:~$ pip install google-api-python-client Collecting google-api-python-client Downloading google_api_python_client-2.187.0-py3-none-any.whl.metadata (7.0 kB) Collecting httplib2<1.0.0,>=0.19.0 (from google-api-python-client) ...(중략)... Installing collected packages: urllib3, uritemplate, pyparsing, pyasn1, protobuf, idna, charset_normalizer, certifi, cachetools, rsa, requests, pyasn1-modules, proto-plus, httplib2, googleapis-common-protos, google-auth, google-auth-httplib2, google-api-core, google-api-python-client Successfully installed cachetools-6.2.4 certifi-2025.11.12 charset_normalizer-3.4.4 google-api-core-2.28.1 google-api-python-client-2.187.0 google-auth-2.45.0 google-auth-httplib2-0.3.0 googleapis-common-protos-1.72.0 httplib2-0.31.0 idna-3.11 proto-plus-1.27.0 protobuf-6.33.2 pyasn1-0.6.1 pyasn1-modules-0.4.2 pyparsing-3.2.5 requests-2.32.5 rsa-4.9.1 uritemplate-4.2.0 urllib3-2.6.2 (venv) eqmaker@debian:~$
Step 4. venv 가상환경 종료
가상 환경에서 빠져나오려면 deactivate 명령을 실행한다.
(venv) eqmaker@debian:~$ deactivate eqmaker@debian:~$
시스템 Python과 venv에서 pip 명령이 다른 이유
눈치 빠른 독자라면 리눅스 프롬프트 환경과 파이썬 venv 환경에서 pip를 실행하는 명령어가 다른 것을 발견 했을 것이다.
리눅스 프롬프트에서는 다음과 같은 형식의 명령어를 사용했다.
python3 -m pip install 파이썬모듈이름
하지만, venv 환경에서는 다음과 같은 형식의 명령어가 사용됐다.
pip install 파이썬모듈이름
이 차이는 pip 사용 방법이 달라졌기 때문이 아니라, 어떤 파이썬 인터프리터를 기준으로 실행되는가라는 기준이 달라졌기 때문이다.
리눅스 기본 프롬프트 환경
리눅스 프롬프트에서는 pip 명령이 특정 파이썬 인터프리터에 연결되어 있지 않을 수 있다. 따라서 python3 -m pip 형태로 실행하면, 현재 사용 중인 python3 인터프리터에 정확히 대응되는 pip 모듈을 호출하게 된다.
즉, 이 방식은 pip를 실행하는 것이 아니고, 해당 파이썬 인터프리터의 pip 모듈을 실행한다는 의미이다.
venv 환경에서의 pip
venv 가상 환경을 활성화하면, 해당 가상 환경의 파이썬 인터프리터와 pip가 우선적으로 사용되도록 PATH가 변경된다. 이 상태에서는 pip install 명령이 자동으로 venv 내부의 파이썬 환경을 기준으로 동작하게 된다.
때문에 venv 환경에서는 python3 -m 처럼 명시적인 인터프리터 지정이 없이 pip install 명령을 사용할 수 있다.
PATH와 Python 인터프리터 기준의 차이
리눅스에서 명령어 실행 순서는 PATH 환경 변수에 의해 결정된다. venv를 활성화하면 ~/venv/bin 디렉토리가 PATH의 가장 앞에 추가된다. 때문에 venv 내부의 python과 pip가 시스템 명령보다 먼저 선택된다.
즉 프롬프트와 venv 환경에서 pip 사용 방법이 달라 보이는 건, pip의 동작 방식이 바뀐 것이 아니라 사용하는 파이썬 인터프리터와 실행 경로가 달라졌기 때문이다.
마무리
데비안 리눅스 환경에서 파이썬 확장 모듈을 설치하려 할 때 마주치는 문제들은, 대부분 pip 사용법의 변화가 아니라 배포판이 시스템 Python 환경을 보호하기 위해 도입한 정책에서 비롯된다. 데비안은 apt와 pip의 충돌을 방지하기 위해 시스템 Python을 externally managed environment로 관리하며, 그 결과 시스템 전역에 대한 직접적인 pip 설치는 제한된다.
파이썬 확장 모듈을 안전하게 사용하는 정석적인 방법은 시스템 Python을 건드리지 않는 venv 기반의 가상 환경을 구성하는 것이다. venv를 사용하면 각 프로젝트별로 독립적인 Python 실행 환경을 만들 수 있으며, pip를 이용한 확장 모듈 설치 역시 문제없이 진행할 수 있다.