파이썬 pip 사용법: 패키지 설치와 PyPI 완벽 정리

pip이 도대체 뭔가요

pip은 내가 직접 만들지 않은 파이썬 라이브러리를 설치해 주는 도구입니다. pip install requests를 실행하면 PyPI(Python Package Index)에서 requests를 찾아, 내 환경에 맞는 버전을 내려받아 파이썬이 설치된 위치의 site-packages 디렉터리에 넣어 줍니다. 이 과정이 끝나면 비로소 import requests가 동작하죠.

python.org, Homebrew, 리눅스 패키지 매니저 등 어디서 받은 Python 3든 pip은 기본으로 함께 설치돼 있습니다. 본격적으로 뭔가 설치하기 전에 먼저 이렇게 확인해 봅시다:

python -m pip --version

pip 버전 정보와 모듈 경로가 출력되면 정상입니다. 만약 명령이 실패한다면, 다음 방법이 가장 확실한 해결책입니다:

python -m ensurepip --upgrade

이렇게 하면 인터프리터에 함께 포함된 사본을 사용해서 현재 Python 환경에 pip를 부트스트랩할 수 있습니다.

python -m pip와 pip의 차이

두 가지 형태를 모두 보게 될 텐데요, 거의 같은 일을 하지만 중요한 차이가 하나 있습니다. python -m pip은 PATH에 잡힌 python, 즉 여러분의 스크립트가 실제로 사용하는 그 python을 쓰는 반면, 그냥 pip은 먼저 검색되는 pip을 쓰는데 이게 항상 같은 건 아니라는 점입니다.

Python을 여러 개 설치해 둔 경우(macOS에선 흔한 상황이죠), 그냥 pip을 쓰다 보면 "라이브러리는 분명히 설치했는데 코드에선 계속 ModuleNotFoundError가 뜬다"는 그 황당한 상황에 빠지게 됩니다.

원칙: 어떤 인터프리터에 패키지가 설치되는지 확실히 하고 싶다면 python -m pip ...을 쓰세요. 상황이 명확한 간단한 작업이라면 그냥 pip을 써도 괜찮습니다.

패키지 설치하기

기본 명령어는 다음과 같습니다:

python -m pip install requests

이 명령어는 requests 패키지와 의존성까지 한 번에 PyPI에서 받아 설치해 줍니다. 잠깐이면 끝나고, 바로 이렇게 쓸 수 있어요:

패키지 여러 개를 한 번에 설치하는 방법:

python -m pip install requests pandas rich

특정 버전으로 고정하기:

python -m pip install "django==5.0.2"
python -m pip install "requests>=2.30,<3"

따옴표는 일부 셸에서 중요합니다. ==나 < 같은 기호를 셸 연산자로 해석하지 않도록 막아주거든요.

업그레이드와 언인스톨

python -m pip install --upgrade requests
python -m pip uninstall requests

--upgrade 옵션은 지정한 조건에 맞는 가장 최신 버전을 받아옵니다. uninstall은 해당 패키지만 제거할 뿐, 함께 설치됐던 의존성 패키지들은 그대로 남아 있습니다. 의존성까지 정리하고 싶다면 따로 지워줘야 해요.

pip 자체를 최신 버전으로 유지하려면 다음 명령어를 사용하세요:

python -m pip install --upgrade pip

몇 달에 한 번씩 돌려주면 좋습니다. 최신 버전의 pip일수록 설치 관련 문제를 더 잘 잡아내고, 의존성 해결 능력도 더 좋거든요.

설치된 패키지 확인하기

python -m pip list
python -m pip show requests

list는 현재 파이썬 환경에 설치된 모든 패키지를 보여줍니다. show requests를 실행하면 해당 패키지의 버전, 설치 위치, 의존성, 라이선스 정보가 출력되는데, "지금 내가 쓰고 있는 버전이 도대체 몇이지?" 싶을 때 아주 유용합니다.

requirements.txt: 의존성 목록 관리하기

프로젝트에 라이브러리가 두세 개만 넘어가도 목록으로 정리해 두는 게 좋습니다. 이 작업은 pip freeze가 알아서 해줍니다:

python -m pip freeze > requirements.txt

이렇게 하면 고정된 의존성이 한 줄에 하나씩 들어간 파일이 만들어집니다:

django==5.0.2
requests==2.31.0
rich==13.7.1

레포를 클론한 사람은 누구든 아래 명령어로 동일한 환경을 그대로 재현할 수 있어요:

python -m pip install -r requirements.txt

pip freeze는 전이(transitive) 의존성까지 포함해서 설치된 모든 패키지를 뽑아냅니다. 완벽한 재현성이 필요하다면 유용하지만, 정작 코드에서 직접 import하는 최상위 라이브러리만 보고 싶을 때는 지저분하게 느껴지죠. 그래서 많은 프로젝트는 직접 사용하는 의존성만 손으로 관리하는 requirements.txt를 두고, 나머지 전이 의존성은 pip가 알아서 풀도록 맡깁니다.

요즘 프로젝트에서는 requirements.txt 대신 pyproject.toml을 쓰는 흐름이 자리 잡고 있습니다(보통 pip-tools, uv, poetry, hatch 같은 도구와 함께 씁니다). "의존성을 파일에 적어두고, 명령 한 줄로 설치한다"는 개념 자체는 동일하고, 파일 포맷이 좀 더 구조화됐을 뿐입니다.

가상환경(virtual environment)에 설치하는 습관 들이기

제대로 된 파이썬 프로젝트라면 예외 없이 가상환경을 하나씩 둬야 합니다. 가상환경은 프로젝트 폴더 안에 전용 python과 전용 패키지 저장소를 갖는 구조라, 한 프로젝트에서 pip install을 해도 다른 프로젝트에는 아무 영향이 없습니다.

두 줄이면 끝나는 세팅입니다:

python -m venv .venv
source .venv/bin/activate    # macOS / Linux
# or .venv\Scripts\activate on Windows

한 번 활성화하고 나면 python -m pip install requests는 venv 안쪽에 패키지를 설치합니다. 시스템 파이썬은 건드리지 않죠. 더 자세한 내용은 가상 환경 페이지에서 다룹니다.

혹시 pip install을 실행했는데 시스템 파이썬에 설치된다는 경고가 뜨거나 --break-system-packages를 붙이라는 메시지가 나오면, 거기서 멈추세요. venv를 만들라는 신호입니다.

pip으로 패키지 설치가 안 될 때

자주 마주치는 실패 유형과 그 의미를 정리해봤습니다.

• Could not find a version that satisfies the requirement … — 대부분 패키지 이름을 잘못 쳤거나, 해당 패키지가 지금 쓰는 파이썬보다 더 최신 버전을 요구하는 경우입니다.
• error: Microsoft Visual C++ 14.0 or greater is required (Windows) — 네이티브 확장이 포함된 패키지라서 C++ 빌드 툴체인이 필요합니다. Microsoft Build Tools를 설치하거나, 미리 빌드된 wheel이 있는지 찾아보세요(유명한 패키지는 대부분 wheel을 제공합니다).
• Permission denied — 루트 권한 없이 시스템 파이썬에 설치하려고 할 때 납니다. 해결책은 sudo pip install이 아니라 가상 환경입니다.
• 설치 후에 ModuleNotFoundError — 거의 대부분 pip install이 스크립트를 실행하는 파이썬이 아닌 다른 파이썬에 패키지를 설치한 경우입니다. macOS/Linux라면 which python과 which pip, Windows라면 where python / where pip로 확인해 보세요. 아니면 아예 확실하게 python -m pip install ... 형태로 쓰는 게 좋습니다.

pip을 대신하는 최신 도구들

이런 이름들을 종종 보게 될 텐데요, 전부 pip과 호환되며 각자 특정 불편함을 해결해 줍니다.

• uv — 훨씬 빠른 설치 및 의존성 해결 도구. 대부분의 pip 명령어를 그대로 대체할 수 있습니다.
• pipx — black, ruff, httpie 같은 CLI 도구를 격리된 venv에 설치해 줘서, 프로젝트 의존성과 충돌 없이 전역에서 쓸 수 있게 해줍니다.
• **poetry**와 hatch — 가상 환경 관리, 의존성 해결, 빌드를 하나로 묶어 주는 프로젝트 관리 도구입니다.

처음부터 이 도구들을 다 알 필요는 없습니다. pip을 먼저 익히고, 그 도구들이 해결해 주는 불편함을 직접 느끼게 됐을 때 손을 뻗으면 됩니다.

다음 단계: 가상 환경

패키지와 가상 환경은 떼려야 뗄 수 없는 짝입니다. 왜 그런지는 이미 살펴봤으니, 다음 페이지에서는 venv를 본격적으로 다뤄봅니다. 생성부터 활성화, 비활성화, 그리고 파이썬 프로젝트를 깔끔하게 유지해 주는 작은 관례들까지 차근차근 짚어보겠습니다.