파이썬 애플리케이션 배포하기: pipx 편

파이썬을 오래 사용해왔지만 파이썬으로 만들어진 프로그램을 배포할 때는 항상 파이썬 가상 환경을 사용했습니다. 

이 글에서 살펴보는 pipx가 사용되는 것은 여러 웹 사이트나 문서에서 많이 봐왔지만, 처음엔 ‘늘 사용하던 파이썬 가상 환경만 사용하면 됐지… 뭘 더 배워야 하나’ 했습니다. 하지만 pipx를 사용하고 나니 제가 콘솔 스크립트가 포함된 파이썬 프로그램을 배포하는 과정이 엄청 지저분했구나 하는 생각이 들었습니다. 여러분도 제가 느낀 이런 천지가 개벽하는 느낌을 받을 수 있으면 좋겠습니다. 그래서 여러분에게도 pipx를 소개하고자 합니다.

프로그램을 개발할 수 있는 프로그래밍 언어는 파이썬을 비롯해 C, C++, 자바, Rust, Golang 등 다양하지만, 여기에서는 파이썬으로 만들어진 프로그램을 배포하는 방법을 살펴보겠습니다. 파이썬을 사용해 개발을 진행하는 경우 일반적으로는 대다수의 개발자가 문서나 샘플을 찾아보거나 또는 ChatGPT와 같은 친구들을 통해 도움을 받아 프로그램을 개발합니다. 그에 반해서 프로그램 배포는 ‘어떻게든 되지 않을까? 그건 쓰는 사람의 몫 아니야?’ 하는 식으로 무관심합니다. 

실제로 프로그램을 개발하기 위해서 사용하는 여러 라이브러리를 설치하는 것은 매우 쉽습니다. 단순히 pip 명령을 사용하는 것만으로도 라이브러리를 설치하거나 업그레이드할 수 있기 때문입니다.

pip install package_name

물론 pip 명령은 기본적으로 PyPI에 등록된 패키지만 가져옵니다. 요즘 많이 사용되는 프로그래밍 언어도 pip와 같은 명령어나 방법을 제공합니다. 자바는 maven이나 gradle 같은 친구들을 사용해 라이브러리를 설치할 수 있고 NodeJS는 npm이나 yarn 명령을 사용해 라이브러리를 설치할 수 있습니다. pip와 마찬가지로 gradle이나 npm 같은 도구도 기본적으로 접속하는 공개된 라이브러리 저장소가 있습니다. 그렇지만 단순히 라이브러리를 설치하는 목적은 프로그램을 개발하기 위해 필요한 것이지, 실제로 우리가 사용하려는 프로그램이 이들 저장소를 통해 제공되지는 않습니다.

Console Script (콘솔 스크립트)

파이썬은 다른 언어와 달리 파이썬 프로그램을 패키징할 때 파이썬 파일을 셸*에서 직접 실행할 수 있도록 구성해두면 운영체제에 해당 패키지를 설치했을 때 실행 파일을 만들어주는 기능이 있습니다.

*셸은 운영체제에서 사용하는 터미널 프로그램을 의미합니다. 윈도우는 “명령 프롬프트”, “파워셸”을, 맥이나 리눅스는 “터미널” 프로그램을 사용해 셸을 시작할 수 있습니다.

이것을 “Console Script (콘솔 스크립트)”로 부릅니다. 콘솔 스크립트를 사용하면 셸에서 빠르게 파이썬 패키지에서 제공하는 기능을 사용할 수 있습니다.

콘솔 스크립트를 사용하지 않는다면

콘솔 스크립트를 사용하지 않는 과정을 먼저 살펴보겠습니다. 예를 들어 Asana에서 데이터를 매일 새벽에 불러와 로컬 데이터베이스에 저장하는 기능을 가진 파이썬 스크립트인 asana_project_sync.py 파일이 있다고 가정해보겠습니다. 이 스크립트를 사용하려면 먼저 파이썬 가상 환경*으로 진입해서 셸에서 파이썬을 직접 실행해야 합니다.

*편의상 맥이나 리눅스 환경의 터미널 프롬프트를 사용합니다.

$ source .venv/bin/activate
$ python asana_project_sync.py

물론 python 명령에 직접 스크립트 파일 이름을 명시하는 것이기 때문에 asana_project_sync.py에는 if __name__ == “__main__” 로 시작하는 곳에서 main()과 함수를 만들어져 있어야 합니다. 

이렇게 셸에서 직접 실행 가능한 파이썬 스크립트가 더 많아지면 자연스레 해당 스크립트를 사용할 때마다 python 명령을 직접 명시해주는 수고로움을 보태야 합니다. 물론 맥이나 리눅스 환경의 파이썬 스크립트면 파일의 첫번째줄에 파이썬 인터프리터의 실행 경로를 명시하고 프로그램에 실행 권한을 제공해야 합니다.

여기까지만 들어도 머리가 어질어질하시죠? 그렇지만 아직 어질어질하실때가 아닙니다. 파이썬 스크립트가 있는 경로를 찾아 들어가서 프로그램을 실행해야 합니다.

정리하면, 셸에서 직접 실행 가능한 파이썬 프로그램을 실행하기 위해 다음과 같은 과정을 거쳐야 합니다.

1. 파이썬 가상 환경 진입
2. pip show 명령으로 파이썬 패키지 설치 위치 확인
3. 패키지 설치 위치로 이동
4. python 명령으로 스크립트 실행

셸에서 직접 실행 가능한 파이썬 스크립트 실행을 위해 이렇게 매번 4번의 과정을 거쳐야만 합니다. 아무리 우리가 셸을 사용하는 데 익숙하다곤 하지만, 프로그램 실행 과정에서 타이핑 오류를 내거나 프로그램에 제공해야 하는 인자를 생략한다거나 하는 실수를 내기도 쉽습니다.

그래서 셸에서 파이썬 스크립트를 바로 사용하기 위해 콘솔 스크립트가 사용됩니다. 콘솔 스크립트는 파이썬 패키징을 할 때 만들어지며, 위 과정에서 설명한 것처럼 터미널에서 명령어로 직접 실행할 수 있습니다. 다행스럽게도 파이썬은 패키징할 때 특정 파이썬 스크립트에 있는 함수 하나를 프로그램 진입점으로 삼아 콘솔 스크립트를 만들어주는 기능이 제공됩니다. 콘솔 스크립트가 제공되는 패키지는 파이썬 패키지를 설치했을 때 셸에서 콘솔 스크립트 이름을 입력하고 실행하기만 하면 됩니다.

예를 들어 스크립트가 실행하는 진입점이 asana_project_sync.py 파일에 있는 main 함수이면 콘솔 스크립트의 이름은 asana_project_sync로 명명할 수 있을 것입니다.

콘솔 스크립트를 사용한다면

이제 우리의 터미널 프로그램에서 콘솔 스크립트를 실행하는 방법을 살펴보겠습니다.

1. 파이썬 가상 환경 진입
2. asana_project_sync 명령 실행

여러분이 보시기에 어떤가요? 앞에서 살펴봤던 과정과 비교해 봐도 콘솔 스크립트를 사용해 파이썬 스크립트를 실행하는 방법이 훨씬 쉬운 것 같죠? 실제로도 콘솔 스크립트를 사용하면 파이썬 스크립트에는 __name__이 __main__인지 비교하는 if 문이 없어도 되기에 훨씬 더 단순한 실행 방법을 가지게 됩니다.

PIPX를 시작하기에 앞서

이제 pipx 이야기를 하겠습니다. 파이썬 가상 환경을 만들고 콘솔 스크립트를 사용해 프로그램을 실행하는 과정으로 만족한다면 pipx 같은 도구가 왜 필요할지 의아할 것입니다. 실제로 pipx를 사용하기 위해서는 파이썬이 설치되어 있어야 하기도 합니다. 이런 점에 있어서는 자바 언어도 마찬가지입니다. 자바로 만들어진 프로그램을 배포할 때 JVM이 설치되는 컴퓨터에 이미 있거나 개발자가 해당 프로그램에 JVM이 함께 배포합니다.

지금까지 살펴본 것처럼 콘솔 스크립트를 사용하면 파이썬 스크립트를 쉽게 실행할 수 있음에도 불구하고 파이썬 가상 환경을 생성해야 한다는 단점이 있습니다. 여러분이 윈도우나 맥 운영체제 사용자면 단순히 ‘시스템에 설치되어 있는 파이썬 환경에 콘솔 스크립트를 제공하는 파이썬 패키지를 설치하면 되지, 뭐가 문제야!’라고 할 수도 있습니다.

하지만 시스템에 설치된 파이썬 환경은 글로벌 환경으로 여기에 직접 설치하게 되면 프로그램마다 사용하는 라이브러리 버전들이 달라 프로그램이 실행 과정에서 문제가 발생하기도 합니다.

더욱이 리눅스 배포본들은 윈도우, 맥과 달리 파이썬으로 구현된 여러 프로그램이 시스템에서 직접 이용되고 있어, 리눅스 배포본 업체에서 직접 파이썬을 컴파일해서 번들링된 배포본 전용 패키지 파일로 제공합니다. 2021년 이전에는 시스템에 번들링된 파이썬 환경(글로벌 환경)에 root 사용자가 직접 관리하는 패키지(이를 외부 패키지로 부릅니다)를 설치하는 것이 가능했지만, 이로 인해 최악의 경우 리눅스를 재설치 해야 하는 상황까지 발생함에 따라 논의를 거쳐 PEP 668이 Accept 되었습니다.

PEP 668에서 권장하는 바에 따르면 파이썬 패키지를 배포할 때 선호되는 방법은 가능한 경우 파이썬 가상 환경을 사용하는 것입니다. 이런 이유로 인해 파이썬 가상 환경이 존재한다고 가정한 것입니다. 

그렇지만 콘솔 스크립트를 사용하기 위해 콘솔 스크립트가 설치된 파이썬 가상 환경을 활성화하고 콘솔 스크립트를 실행하는 것은 불편할 수밖에 없죠. 무엇보다 다수의 사용자가 이용하게 만드는 과정에서 “가상 환경”을 만들고 파이썬 가상 환경을 활성화하는 과정부터 순탄치 않을 가능성이 높습니다.

PIPX 설치하기

Flask 개발자인 Armin Ronacher는 콘솔 스크립트를 셸에서 파이썬 가상 환경에 진입하지 않고도 사용할 수 있도록 해주는 파이썬 프로그램인 pipsi라는 프로그램을 개발했습니다.

파이썬 패키징 위원회(Python Packaging Authority)는 pipsi와 NodeJS의 npx에서 영향을 받아 콘솔 스크립트가 제공되는 파이썬 패키지 관리 도구인 pipx를 개발했습니다. pipx를 사용해 콘솔 스크립트가 제공되는 파이썬 패키지를 설치하면 사용자가 파이썬 가상 환경을 만들고 가상 환경을 활성화하고 콘솔 스크립트를 실행하는 과정을 거치지 않아도 됩니다.

pipx를 사용하려면 먼저 파이썬 글로벌 환경에 먼저 pipx를 설치해야 합니다. 운영체제별로 다음과 같이 설치합니다.

윈도우: 관리자 모드의 “명령 프롬프트” 또는 “파워셸”에서 실행합니다.

> pip install pipx

맥: homebrew가 설치되어 있을 때만 brew 명령을 사용합니다.

$ sudo pip install pipx

$ brew install pipx

리눅스(1): 데비안 또는 우분투 계열

$ sudo apt install pipx

리눅스(2): 레드햇 계열의 모든 리눅스

$ sudo dnf install pipx

리눅스의 경우 앞에서 언급한 것처럼 번들링된 파이썬이 설치됩니다. 여기에 root 사용자가 직접 패키지를 설치할 수 없으므로 배포본 저장소에서 직접 제공하는 패키지를 설치합니다. pipx를 설치한 다음에는 반드시 다음 명령을 실행해야 합니다.

$ pipx ensurepath

pipx 패키지를 설치하고 ensurepath 명령까지 실행했으면 이제 pipx를 사용해 패키지를 설치할 차례입니다.

PIPX로 패키지 설치하기

pipx로 패키지를 설치하려면 다음과 같이 합니다.

$ pipx install package_name

pipx install로 설치된 파이썬 패키지의 콘솔 스크립트는 <User Folder>/.local/bin 폴더 아래에 바로가기가 만들어집니다. 예제로 실행해볼 파이썬 패키지로 cowsay를 설치하고 실행하겠습니다.

$ pipx install cowsay
$ cowsay moooo

  -----
< moooo >
  -----
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

cosway는 유닉스 터미널에서 아스키 문자 기반으로 그림을 표시하는 아스키아트와 메시지를 출력하는 프로그램으로 펄(Perl)을 비롯하여 파이썬 패키지로도 만들어져 있습니다.

pipx로 패키지를 설치하기만 하면 콘솔 스크립트 실행은 일반적인 프로그램을 실행하는 것과 크게 다르지 않습니다. pipx는 파이썬 패키지를 설치하기 위해 기본적으로 사용자 홈 폴더에 격리된 파이썬 가상 환경을 자동으로 생성합니다. 이 환경을 shared libs라고 합니다. 이렇게 격리된 가상 환경에 파이썬 패키지를 설치하고, <User Folder>/.local/bin 폴더 아래에 콘솔스크립트의 바로가기(리눅스나 맥은 심볼릭 링크)를 생성합니다.

pipx에서 패키지 제거하기

pipx를 사용해 설치한 패키지를 더 이상 사용하지 않는다면 시스템에서 제거해야 합니다. 앞에서 설치한 cowsay 패키지가 대표적으로 한 번만 사용하고 사용하지 않는 패키지입니다. 다음과 같이 패키지를 제거할 수 있습니다.

$ pipx uninstall package_name

이렇게 제거된 파이썬 패키지는 <User Folder>/.local/bin 폴더에서도 콘솔 스크립트의 바로가기가 삭제됩니다.

pipx 더 살펴보기

앞에서 pipx를 사용해 파이썬 패키지를 설치하고 제거하는 방법을 살펴보았습니다. 그럼 이제 이런 궁금증이 생길지도 모르겠습니다.

Q. pipx가 있으면 pip는 더 이상 사용하지 않는 것인가요?

Q. pipx를 사용하면 pipenv나 poetry 같은 도구는 안 써도 되나요?

Q. pipx를 이미 설치된 pipx를 사용해 설치할 수도 있나요?

첫 번째 궁금증부터 살펴보면 pipx는 실제로는 pip를 한 번 더 감싼 도구이기 때문에 pip를 사용하지 않는 것은 아닙니다. 어디까지나 콘솔 스크립트가 제공되는 파이썬 패키지 배포에 사용되는 도구라고 생각하시면 됩니다.

두 번째 궁금증에 대한 답입니다. pipx는 파이썬 패키지 배포에 사용되는 도구지만, pipenv나 poetry는 파이썬 패키지를 개발하기 위해 사용되는 도구이기 때문에 다른 성격의 도구라고 말할 수 있습니다. 다만 이들 도구는 콘솔 스크립트를 제공하기 때문에 pipx 명령으로 설치해서 사용하기도 합니다.

세 번째 궁금증에 대한 답은 권장되지 않는다 입니다. 별도의 pipx-in-pipx 프로젝트를 통해 시도할 수 있습니다. 하지만 권장되지 않으니까 가능하면 시도하지 않기를 바랍니다.

pipx가 유용한 경우는 파이썬 패키징을 위해 사용하는 pipenv, poetry, pdm과 파이썬 패키지 환경을 구성해주는 django-admin, cookiecutter 와 같이 파이썬 버전에 상관없이 사용하는 도구를 사용할 때입니다. 시스템에 파이썬 3.7, 3.8, 3.9, 3.10, 3.11, 3.12 등이 모두 설치되어 있다고 한다면 pipenv, poetry 같은 도구를 모든 파이썬 환경에 설치하는 것은 불편하기도 할뿐더러 문제를 일으킬 소지도 있습니다.

하나 더, 리눅스 배포본에서 기본으로 번들링되어 제공하는 pipx 패키지는 그 버전이 매우 낮습니다. 가능하다면 최신 pipx 패키지 파일을 찾아 설치하시길 권장합니다. 이 글을 쓰는 당시의 pipx 최신 버전은 1.4.3입니다.

마무리

이 글에서 설명하진 않았지만 pipx는 pypi에서 패키지를 설치하는 것 외에도 사용자가 지정하는 외부 패키지 저장소에서 패키지를 설치하는 것도 가능합니다. 이 과정에서 사용자 인증 방식에 대한 부분도 있는데 이 부분은 여러분이 궁금해하시면 답글 달아드릴게요.

우리는 어떤 프로그램을 사용하기 위해 운영체제에 “프로그램 설치”란 과정을 거쳐 프로그램을 사용하게 됩니다. 우리가 일상적으로 사용하는 오피스 프로그램, 크롬 웹 브라우저, 노션과 같은 프로그램이 바로 이런 과정을 거치게 됩니다. 프로그램을 실행하는 운영체제가 윈도우면 “.exe” 확장자를 가진 파일이 프로그램을 실행하게 될 것이고, 리눅스나 맥*이면 실행 권한을 가지고 있는 파일이기만 하면 됩니다.

*맥은 GUI 프로그램을 배포하기 위해 별도로 사용되는 App 패키징 방식이 있습니다. 이 방식은 터미널에선 직접 사용할 수 없습니다.

하지만 우리가 별도로 만든 프로그램이라면 어떨까요? 떠올리기 쉬운 방법은 프로그램 구동에 필요한 라이브러리들과 실행 파일을 모으고, “인스톨러” 프로그램을 사용해서 “인스톨 패키지”를 만들고, 프로그램 실행이 허락되는 운영체제에서 “인스톨 프로그램”을 사용해 설치하는 것입니다. 

파이썬도 여러 운영체제에 우리가 만든 프로그램을 배포하기 위해 개별 운영체제에서 실행 가능한 파일로 만들기 위해 cx_freeze나 pyinstaller 같은 라이브러리를 사용할 수 있습니다.

예전과 달리 요즘은 스마트폰의 영향으로 프로그램을 설치하고 삭제하는 행동이 숨 쉬는 것보다 쉬워진 것 같기도 한데요. 이전 글 ‘개발 런타임 환경 구축하기 - 파이썬 pyenv편’에서 “프로그램 개발 환경”을 언급했을 때처럼, 예전엔 프로그램을 윈도우에 설치하는 것도 꽤 어렵고 힘든 일에 속했습니다. 믿어지지 않으시죠? 여러분 주변에 1990 ~ 2010년 사이에 컴퓨터를 사용하던 분들에게 물어보시면 ‘넌덜머리 난다’라는 말을 하시는 분이 있을 겁니다.

지금까지 pipx로 CLI 실행 파일을 제공하는 파이썬 프로그램을 파이썬이 설치된 환경에 쉽게 설치하는 방법을 살펴봤습니다. 다음에 뵙겠습니다.

요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.