데비안 리눅스 파이썬 패키지 설치: venv 사용법

데비안 리눅스에서는 pip를 사용할 수 없다?

파이썬은 여러 플랫폼에서 폭넓게 활용되는 프로그래밍 언어로, 방대한 추가 패키지를 통해 복잡한 기능을 비교적 짧은 코드로 사용할 수 있다. 따라서 대부분의 파이썬 프로그램은 실행하는 데 추가 패키지를 필요로 하며, 이러한 패키지를 설치할 때 흔히 사용하는 도구가 pip다.

문제는 데비안 리눅스에는 기본적으로 pip가 포함되어 있지 않으며, 설치하더라도 패키지를 바로 설치할 수 없다는 것이다.

eqmaker@debian:~$ sudo apt install python3-pip -y
Installing:                     
  python3-pip

Installing dependencies:
  binutils                   gcc                        libcrypt-dev            libjs-sphinxdoc    make
... (중략) ...

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: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:~$ 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. ...(이하 생략)

데비안 리눅스에서 venv로 파이썬 패키지 설치하기

데비안 패키지로 제공되는 파이썬 패키지는 apt를 이용해 설치할 수 있으며, 독립 실행형 파이썬 어플리케이션은 pipx를 이용하는 방법도 있다. 하지만 특정 파이썬 프로그램에 필요한 라이브러리를 설치하려는 경우에는 venv 기반의 가상 환경 안에서 pip를 사용하는 방법이 제일 낫다.

venv는 기존 파이썬 인터프리터를 기반으로 별도의 패키지 설치 경로와 실행 환경을 구성하는 기능이다. 시스템 파이썬의 영역과 분리되므로 가상 환경 안에서는 pip를 이용해 필요한 파이썬 패키지를 설치할 수 있다.

1. Step 1. 데비안에 python3-venv 설치

   일단 apt를 이용해 python3-venv 패키지를 설치한다. 이 패키지에는 파이썬 가상 환경을 생성하는 데 필요한 구성 요소가 포함되어 있으며, 가상 환경을 만들면 해당 환경에서 사용할 pip도 함께 준비된다.

   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:~$ 

2. Step 2. venv 가상 환경 생성

   가상 환경을 생성할 디렉토리로 이동한 다음 python3 -m venv 경로이름 명령과 가상 환경의 경로를 입력한다. 본 필자는 홈 디렉토리에 venv라는 가상 환경을 만들고 ls -l을 통해 가상 환경용 디렉토리가 생성된 것을 확인했다.

   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:~$ 

3. Step 3. venv 가상 환경 활성화

   생성한 가상 환경을 현재 셸에서 사용하려면 다음과 같이 활성화 스크립트를 불러온다.

   eqmaker@debian:~$ source ~/venv/bin/activate
   (venv) eqmaker@debian:~$ 

   가상 환경이 활성화되면 프롬프트 앞에 (venv)가 표시된다. 이제부터 시스템에 설치된 파이썬 환경이 아닌 venv 디렉토리의 파이썬 인터프리터와 pip가 사용된다.

4. Step 4. venv에서 파이썬 패키지 설치

   가상 환경이 활성화된 상태에서는 pip를 이용해 필요한 파이썬 패키지를 설치할 수 있다. 다음 예에서는 google-api-python-client 패키지를 설치한다.

   (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:~$ 

5. Step 5. venv 가상 환경 종료

   가상 환경 사용을 마치고 시스템의 기본 셸 환경으로 돌아가려면 deactivate 명령을 이용한다.

   (venv) eqmaker@debian:~$ deactivate
   eqmaker@debian:~$ 

   프롬프트에서 (venv) 표시가 사라지면 가상 환경이 비활성화된 것이다. 가상 환경과 설치한 패키지가 삭제되는 것은 아니므로, 필요할 때 활성화 스크립트를 다시 불러와 사용할 수 있다.

데비안 리눅스 콘솔과 venv에서 pip 명령이 다른 이유

눈치 빠른 독자 제위께서는 콘솔과 venv 환경에서 사용한 pip 실행 명령이 서로 다르다는 것을 보셨을 것이다.

시스템 Python 환경에서는 다음과 같은 형식의 명령을 사용했다.

반면 venv 환경에서는 다음과 같이 입력했다.

이 차이는 pip의 사용 방법이나 동작이 달라졌기 때문이 아니라, 어떤 파이썬 인터프리터와 연결된 pip를 실행하는지 지정하는 방법이 달라 보이는 것이다.

마무리

데비안 리눅스에서 파이썬 패키지를 설치할 때 발생하는 문제는 pip의 사용 방법이 바뀌었기 때문이 아니라, 배포판이 시스템 환경을 보호하기 위해 도입한 패키지 관리 정책에서 비롯된다. 데비안은 apt와 pip가 같은 시스템 파이썬 환경에 개입하면서 발생할 수 있는 패키지 및 의존성 충돌을 방지하기 위해 시스템 파이썬을 externally managed environment로 지정했다. 그 결과 시스템 파이썬을 대상으로 하는 pip 패키지 설치는 기본적으로 제한된다.

데비안 패키지로 제공되는 파이썬 패키지는 apt로 설치하고, 독립 실행형 파이썬 어플리케이션은 필요에 따라 pipx를 사용할 수 있다. 특정 프로젝트에 필요한 파이썬 패키지를 설치하려면 venv 기반의 가상 환경을 구성하고 그 안에서 pip를 사용하는 것이 적합하다.

venv를 사용하면 시스템 파이썬의 패키지 설치 영역을 직접 변경하지 않고 프로젝트별 패키지와 의존성을 별도로 관리할 수 있다. 이를 통해 서로 다른 프로그램이 요구하는 패키지 버전의 충돌을 줄이고, 데비안이 관리하는 시스템 환경도 안전하게 유지할 수 있다.

FAQ

데비안 리눅스에서 pip를 이용해 파이썬 패키지를 설치할 수 없는 이유는?

데비안 12 북웜(Bookworm)부터 배포판이 제공하는 시스템 파이썬이 externally managed environment로 지정되어, pip를 이용한 시스템 전역 패키지 설치가 기본적으로 제한된다. 이는 apt와 pip가 관리하는 패키지 및 의존성이 서로 충돌하는 것을 방지하기 위한 정책이다.

apt, venv, pipx의 차이는?

apt는 데비안 리포지토리에서 제공하는 시스템 패키지를 설치하고 관리한다. venv는 특정 프로젝트에 필요한 파이썬 패키지를 별도의 가상 환경에 설치할 때 사용한다. pipx는 명령행에서 독립적으로 실행하는 파이썬 어플리케이션을 각각 분리된 가상 환경에 설치하고 실행할 때 적합하다.

데비안 리눅스에서 파이썬 프로그램을 실행하기 위해 venv와 pipx 중 무엇을 사용해야 하는가?

직접 작성하거나 실행할 파이썬 프로그램에 필요한 라이브러리를 설치하려면 venv를 사용하는 것이 적합하다. 반면 다른 사람이 만든 파이썬 기반 명령행 어플리케이션을 시스템 명령처럼 설치해 사용하려면 pipx가 편리하다.

파이썬 프로그램을 실행하기 위해 굳이 venv를 사용해야 하는 이유는?

파이썬 생태계의 모든 패키지가 데비안 리포지토리에 등록되어 있는 것은 아니며, 같은 패키지라도 프로젝트마다 요구하는 버전이 다를 수 있다. venv를 사용하면 시스템 파이썬을 변경하지 않고 프로젝트에 필요한 패키지와 버전을 별도로 설치할 수 있다. 서로 다른 프로젝트 사이의 의존성 충돌도 줄일 수 있다.

venv 가상 환경과 가상 머신은 무엇이 다른가?

venv는 기존 파이썬 인터프리터를 기반으로 패키지 설치 경로와 실행 환경을 분리하는 기능이다. 별도의 운영체제나 하드웨어를 가상화하지 않으므로 빠르고 가볍다. 가상 머신은 가상 하드웨어와 별도의 운영체제 전체를 실행하므로 더 강한 격리를 제공하지만 더 많은 시스템 자원을 사용한다.

venv를 사용하려면 python3-pip를 먼저 설치해야 하는가?

반드시 그럴 필요는 없다. 데비안에서 python3-venv를 설치하고 python3 -m venv 가상환경경로를 실행하면 일반적으로 해당 가상 환경에서 사용할 pip가 함께 준비된다. 시스템 Python에서 직접 pip를 사용하려는 경우에만 python3-pip 패키지가 별도로 필요할 수 있다.

venv 가상 환경을 활성화하지 않고 사용하는 방법은?

사용할 수 있다. 활성화는 가상 환경의 bin 디렉토리를 PATH 앞부분에 추가해 python과 pip 명령을 편리하게 사용하는 과정이다. 활성화하지 않더라도 가상환경경로/bin/python처럼 실행 파일의 전체 경로를 지정하면 해당 가상 환경을 사용할 수 있다.

deactivate를 실행하면 설치한 패키지가 삭제되는가?

삭제되지 않는다. deactivate는 현재 셸에서 가상 환경 사용을 끝내고 기존의 PATH를 복원할 뿐이다. 가상 환경 디렉토리와 그 안에 설치한 패키지는 그대로 유지되며, 활성화 스크립트를 다시 실행하면 계속 사용할 수 있다.

--break-system-packages 옵션을 사용해도 되는가?

--break-system-packages를 지정하면 externally managed environment의 제한을 무시하고 시스템 Python 환경에 패키지를 설치할 수 있다. 그러나 데비안 패키지와 의존성 충돌을 일으키거나 시스템 프로그램의 동작에 영향을 줄 수 있으므로 일반적인 해결 방법으로 권장하지 않는다. 특별한 이유가 없다면 apt, venv 또는 pipx를 사용하는 것이 안전하다.

설치한 파이썬 패키지는 어디에 저장되는가?

venv에서 설치한 패키지는 해당 가상 환경의 lib/pythonX.Y/site-packages/ 디렉토리에 저장된다. 따라서 한 가상 환경에 설치한 패키지는 기본적으로 다른 가상 환경이나 시스템 Python에서 직접 사용할 수 없다.