Python 강좌 : 제 28강 - PIP 설치

PIP(Package Installer for Python)

PIP(Package Installer for Python)는 Python으로 작성된 패키지 소프트웨어를 설치하고 관리하는 데 사용하는 패키지 관리자입니다.

기본적으로 PyPI(Python Package Index)에 등록된 패키지를 내려받아 설치합니다.

명령 줄 인터페이스만으로도 손쉽게 소프트웨어 패키지를 설치할 수 있습니다.

PIP는 Python 설치 시 함께 설치되므로, 별도로 설치하지 않아도 사용할 수 있습니다.

Python에는 math, random, json처럼 설치 없이 바로 사용할 수 있는 표준 라이브러리(Standard Library)가 포함되어 있습니다.

하지만 수치 계산(numpy), 데이터 분석(pandas), 웹 요청(requests), 이미지 처리(opencv-python)처럼 표준 라이브러리에 없는 기능은 다른 개발자가 만들어 공개한 외부 패키지를 설치해 사용합니다.

PIP는 이런 외부 패키지를 찾아 내려받고, 현재 Python에서 import할 수 있도록 설치해 주는 도구입니다.

이번 강좌에서는 패키지와 PyPI, 의존성의 개념을 먼저 알아본 다음, PIP로 패키지를 설치·확인·삭제하고 설치 목록을 파일로 관리하는 방법을 다룹니다.

이 강좌의 명령어는 Windows의 명령 프롬프트(cmd)나 PowerShell, 리눅스나 macOS의 터미널(Shell)에서 실행합니다.

Python 인터프리터(>>>) 안에서 실행하는 명령어가 아니므로 주의합니다.

>>> 안에서 pip install numpy를 입력하면 Python 문법이 아니므로 SyntaxError가 발생합니다. 이 경우 exit()로 인터프리터를 종료한 다음 터미널에서 실행합니다.

패키지와 PyPI

모듈(module)은 Python 코드가 작성된 하나의 .py 파일이며, 패키지(package)는 여러 모듈을 폴더 구조로 묶은 것입니다.

PIP가 다루는 “패키지”는 이보다 넓은 의미로, 이름과 버전을 붙여 배포할 수 있게 묶은 소프트웨어 단위를 말합니다. 이를 배포 패키지(distribution package)라고도 부릅니다.

예를 들어, numpy 2.5.1은 하나의 배포 패키지이며, 설치하면 import numpy로 사용할 수 있는 numpy 패키지 폴더가 생깁니다.

PyPI(Python Package Index)는 이런 배포 패키지가 등록되는 공식 패키지 저장소입니다.

누구나 패키지를 등록할 수 있으며, PIP는 별도의 설정이 없다면 PyPI에서 패키지를 검색하고 내려받습니다.

PyPI에는 같은 패키지의 여러 버전이 함께 등록되어 있으므로, 최신 버전뿐만 아니라 원하는 과거 버전도 설치할 수 있습니다.

PyPI의 패키지 파일은 크게 두 가지 형태로 제공됩니다.

휠(wheel, .whl)은 이미 빌드가 끝난 설치용 파일로, 압축을 풀어 복사하기만 하면 되므로 설치가 빠릅니다. C언어 등으로 작성된 확장 모듈이 포함된 패키지는 운영체제와 Python 버전별로 휠이 따로 제공됩니다.

소스 배포판(sdist, .tar.gz)은 소스 코드 그대로의 파일로, 설치할 때 빌드 과정을 거칩니다. 사용하는 환경에 맞는 휠이 없다면 PIP는 소스 배포판을 내려받아 빌드를 시도합니다.

• Tip : 아주 최신 Python 버전에서 일부 패키지의 설치가 실패한다면, 해당 버전용 휠이 아직 제공되지 않아 소스 빌드를 시도하다 실패하는 경우가 많습니다. 오류 메시지에 building wheel, compiler 같은 문구가 있다면 이 경우를 의심합니다.

PyPI에 등록된 이름은 신뢰할 수 있는 이름인지 확인해야 합니다.

유명한 패키지와 철자가 비슷한 이름으로 악성 패키지를 등록하는 경우가 있으므로, 패키지 이름은 공식 문서나 PyPI 페이지에서 확인한 다음 설치합니다.

의존성(Dependency)

대부분의 패키지는 모든 기능을 직접 구현하지 않고, 다른 패키지의 기능을 가져다 사용합니다.

이처럼 어떤 패키지가 동작하기 위해 필요한 다른 패키지를 의존성(dependency) 또는 의존 패키지라 부릅니다.

PIP로 패키지를 설치하면, 그 패키지의 의존성도 자동으로 함께 설치됩니다.

from importlib.metadata import version, requires

print(version("requests"))
for requirement in requires("requests"):
    print(requirement)

결과

2.34.2
charset_normalizer<4,>=2
idna<4,>=2.5
urllib3<3,>=1.26
certifi>=2023.5.7
PySocks!=1.5.7,>=1.5.6; extra == “socks”
chardet<8,>=3.0.2; extra == “use-chardet-on-py3”

importlib.metadata 모듈은 설치된 패키지의 정보(메타데이터)를 Python 코드에서 읽을 때 사용하는 표준 라이브러리입니다. (Python 3.8 이상)

version(패키지 이름)은 설치된 버전을, requires(패키지 이름)은 그 패키지가 요구하는 의존성 목록을 반환합니다.

결과를 보면 requests는 charset_normalizer, idna, urllib3, certifi를 필요로 하며, 각각 사용할 수 있는 버전의 범위도 함께 지정되어 있습니다.

예를 들어, urllib3<3,>=1.26은 1.26 이상, 3 미만의 urllib3가 필요하다는 의미입니다.

마지막 두 줄의 extra == "socks"처럼 조건이 붙은 의존성은 requests[socks]와 같이 추가 기능을 선택해 설치할 때만 설치됩니다.

• Tip : 결과의 버전과 의존성 목록은 설치된 requests의 버전에 따라 달라집니다.

의존성은 다시 자신의 의존성을 가질 수 있으므로, 패키지 하나를 설치해도 여러 개의 패키지가 연쇄적으로 설치될 수 있습니다.

이때 두 패키지가 같은 의존 패키지의 서로 맞지 않는 버전을 요구하면 의존성 충돌(dependency conflict)이 발생합니다.

예를 들어, 패키지 A는 urllib3<2를, 패키지 B는 urllib3>=2를 요구한다면 두 조건을 동시에 만족하는 버전이 없습니다.

PIP는 설치할 때 의존성 조건을 검사하여, 만족할 수 없는 경우 ResolutionImpossible 오류를 출력하거나 충돌이 생긴 패키지를 경고로 알려 줍니다.

python -m pip check

결과

No broken requirements found.

python -m pip check는 현재 설치된 패키지들의 의존성 조건이 모두 만족되는지 검사합니다.

문제가 없다면 No broken requirements found.가 출력되고, 버전이 맞지 않거나 빠진 의존 패키지가 있다면 해당 패키지와 요구 조건을 출력합니다.

패키지를 여러 번 설치·업그레이드한 뒤 프로그램이 이상하게 동작한다면, 가장 먼저 확인해 볼 명령어입니다.

PIP 실행 방법

PIP는 독립된 프로그램이 아니라 특정 Python에 설치된 모듈입니다.

컴퓨터에 Python이 여러 개 설치되어 있다면 PIP도 Python마다 따로 있으며, 어떤 PIP로 설치했는지에 따라 패키지가 설치되는 위치가 달라집니다.

그러므로, PIP를 실행할 때는 어떤 Python의 PIP를 실행하는지가 중요합니다.

python -m pip --version

결과

pip 26.1.2 from E:\Miniconda\Lib\site-packages\pip (python 3.14)

PIP는 pip 명령어 형태로도 실행할 수 있지만, python -m pip 명령어 형태로 실행하는 것을 권장합니다.

-m 옵션은 모듈을 스크립트처럼 실행하는 옵션으로, python -m pip는 현재 실행한 python에 연결된 PIP를 실행합니다.

여러 버전의 Python이 설치되어 있거나 가상 환경을 사용하는 경우, pip 명령어는 의도하지 않은 다른 Python의 PIP를 실행할 수 있습니다.

python -m pip를 사용하면 어떤 Python에 패키지를 설치하는지 명확해집니다.

결과의 (python 3.14)를 통해 PIP가 연결된 Python 버전을, from 뒤의 경로를 통해 패키지가 설치되는 위치를 확인할 수 있습니다.

• Tip : 출력되는 PIP 버전과 경로는 설치 환경마다 다릅니다.

import sys

print(sys.executable)
print(sys.prefix)

결과

E:\Miniconda\python.exe
E:\Miniconda

“분명히 설치했는데 ModuleNotFoundError가 발생한다”면, 대부분 패키지를 설치한 Python과 코드를 실행한 Python이 서로 다른 경우입니다.

코드 안에서 sys.executable을 출력하면 지금 코드를 실행하고 있는 Python 실행 파일의 경로를, sys.prefix는 그 Python이 설치된 폴더를 확인할 수 있습니다.

이 경로의 Python으로 경로\python.exe -m pip install 패키지 이름을 실행하면, 코드를 실행하는 Python에 정확히 설치할 수 있습니다.

• Tip : VS Code, PyCharm 같은 편집기는 각자 선택된 Python(인터프리터)으로 코드를 실행합니다. 편집기에서 선택한 인터프리터와 터미널의 python이 같은지 확인합니다.

py -m pip --version
py -3.14 -m pip --version

Windows에서 Python 공식 설치 파일로 설치했다면, py 명령어(Python Launcher)를 사용할 수 있습니다.

py -m pip는 설치된 Python 중 기본 버전의 PIP를 실행하며, py -버전 -m pip로 특정 버전의 PIP를 실행할 수 있습니다.

python 명령어를 찾을 수 없다는 오류가 발생할 때도 py 명령어로 실행할 수 있습니다.

• Tip : python 명령어가 인식되지 않는다면, Python 설치 시 Add python.exe to PATH 옵션을 선택했는지 확인합니다. 리눅스나 macOS에서는 python 대신 python3를 사용하는 경우가 많습니다.

패키지 설치

패키지 설치는 PIP의 가장 기본적인 기능입니다.

install 명령어는 PyPI에서 패키지를 찾아 현재 환경에 맞는 파일을 내려받고, 의존성까지 함께 설치합니다.

python -m pip install numpy
python -m pip install numpy==2.5.1
python -m pip install "numpy>=2.0"
python -m pip install numpy pandas matplotlib

python -m pip install 패키지 이름으로 최신 버전의 패키지를 설치할 수 있습니다.

패키지 이름==버전으로 특정 버전을 설치할 수 있습니다.

패키지 이름>=버전과 같이 비교 연산자를 사용해 설치할 버전의 범위를 지정할 수 있습니다.

>, < 기호는 셸에서 리다이렉션으로 해석되므로, 비교 연산자를 사용할 때는 따옴표로 감싸야 합니다.

따옴표 없이 pip install numpy>=2.0을 실행하면, 셸이 >=2.0 부분을 “=2.0이라는 파일로 출력을 저장하라”는 의미로 해석하여 버전 조건 없이 설치되고 =2.0 파일이 생길 수 있습니다.

여러 패키지를 공백으로 구분하여 한 번에 설치할 수도 있습니다.

설치가 완료되면 Successfully installed 패키지 이름-버전이 출력됩니다.

버전을 지정하지 않으면 설치할 수 있는 최신 버전이 설치되므로, 설치하는 시점에 따라 다른 버전이 설치될 수 있습니다.

다른 사람과 같은 결과를 내야 하는 프로젝트라면 ==으로 버전을 고정하고, 라이브러리처럼 다양한 환경에서 쓰여야 한다면 >=처럼 범위로 지정하는 것이 일반적입니다.

이미 조건을 만족하는 버전이 설치되어 있다면, PIP는 다시 설치하지 않고 Requirement already satisfied를 출력합니다.

• Tip : OpenCV 라이브러리는 opencv-python으로 설치할 수 있습니다. 이처럼 설치할 때의 패키지 이름과 import할 때의 모듈 이름(cv2)이 다른 경우도 있습니다.

import numpy

print(numpy.__version__)

결과

2.5.1

Python에서 import 모듈 이름과 모듈.__version__을 통하여 패키지의 정상 설치 유/무와 버전을 확인할 수 있습니다.

설치되지 않은 모듈을 불러오면 ModuleNotFoundError가 발생합니다.

from importlib.metadata import version, PackageNotFoundError

try:
    print(version("opencv-python"))
except PackageNotFoundError as e:
    print("설치되지 않음:", e)

결과

설치되지 않음: No package metadata was found for opencv-python

모든 패키지가 __version__ 속성을 제공하는 것은 아니므로, 버전을 확인할 때는 importlib.metadata.version()을 사용하는 방법이 더 일반적입니다.

version()에는 import 이름(cv2)이 아니라 설치할 때 사용한 패키지 이름(opencv-python)을 전달합니다.

패키지가 설치되어 있지 않다면 PackageNotFoundError가 발생하므로, 예제처럼 설치 여부를 확인하는 용도로도 사용할 수 있습니다.

• Tip : 결과는 opencv-python이 설치되지 않은 환경에서 실행한 결과입니다.

import requests
import numpy

print(requests.__file__)
print(numpy.__file__)

결과

E:\Miniconda\Lib\site-packages\requests\_init__.py
E:\Miniconda\Lib\site-packages\numpy\_init__.py

PIP로 설치한 패키지는 해당 Python의 site-packages 폴더에 저장됩니다.

모듈.__file__을 출력하면 불러온 모듈이 실제로 어느 위치의 파일인지 확인할 수 있습니다.

같은 이름의 패키지가 여러 곳에 설치되어 있을 때, 의도한 위치의 패키지를 불러왔는지 확인할 때 유용합니다.

패키지 업그레이드

패키지는 기능 추가, 버그 수정, 보안 문제 해결을 위해 꾸준히 새 버전이 배포됩니다.

이미 설치된 패키지는 install을 다시 실행해도 업그레이드되지 않으므로, 업그레이드 옵션을 지정해야 합니다.

python -m pip install --upgrade pip
python -m pip install --upgrade numpy

python -m pip install --upgrade 패키지 이름으로 이미 설치된 패키지를 최신 버전으로 업그레이드할 수 있습니다.

--upgrade 옵션은 -U로 줄여 사용할 수 있습니다.

python -m pip install --upgrade pip로 PIP 자체를 최신 버전으로 업그레이드할 수 있습니다.

패키지를 업그레이드하면 그 패키지를 사용하는 다른 패키지와 호환되지 않는 버전이 될 수도 있습니다.

새 버전에서 함수 이름이나 동작이 바뀌는 경우도 있으므로, 작동 중인 프로젝트의 패키지를 업그레이드할 때는 변경 사항을 확인하고 업그레이드 후 python -m pip check로 의존성을 검사하는 것이 좋습니다.

• Tip : Windows에서 pip install --upgrade pip로 PIP를 업그레이드하면 실행 중인 pip.exe를 교체할 수 없어 오류가 발생할 수 있습니다. PIP 업그레이드는 반드시 python -m pip로 실행합니다.

설치된 패키지 확인

설치된 패키지의 목록과 버전을 확인하면, 프로젝트에 필요한 패키지가 설치되어 있는지, 어떤 버전을 사용하고 있는지 알 수 있습니다.

python -m pip list
python -m pip list --outdated

python -m pip list를 통하여 설치된 모든 패키지와 버전을 확인할 수 있습니다.

--outdated 옵션을 추가하면 새 버전이 존재하는 패키지만 출력합니다.

--outdated는 PyPI에서 최신 버전을 조회하므로 인터넷 연결이 필요하며, 패키지가 많으면 시간이 걸릴 수 있습니다.

목록에는 직접 설치한 패키지뿐만 아니라 의존성으로 함께 설치된 패키지도 모두 포함됩니다.

python -m pip show numpy

결과

Name: numpy
Version: 2.5.1
Summary: Fundamental package for array computing in Python
Home-page: https://numpy.org
…
Location: E:\Miniconda\Lib\site-packages
Requires:
Required-by: contourpy, datasets, matplotlib, pandas, transformers

python -m pip show 패키지 이름으로 특정 패키지의 상세 정보를 확인할 수 있습니다.

Version은 설치된 버전, Location은 설치 경로를 의미합니다.

Requires는 이 패키지가 의존하는 패키지이며, Required-by는 이 패키지를 필요로 하는 패키지입니다.

numpy는 Requires가 비어 있으므로 다른 패키지 없이 동작하며, Required-by를 보면 pandas, matplotlib 등이 numpy를 사용하고 있음을 알 수 있습니다.

Required-by에 패키지가 있다면, 이 패키지를 삭제하거나 다른 버전으로 바꿀 때 해당 패키지들이 영향을 받을 수 있습니다.

• Tip : 결과의 버전, 경로, 의존 패키지 목록은 설치 환경마다 다릅니다.

패키지 삭제

더 이상 사용하지 않는 패키지나, 문제가 생겨 다시 설치해야 하는 패키지는 삭제할 수 있습니다.

python -m pip uninstall numpy
python -m pip uninstall -y numpy

python -m pip uninstall 패키지 이름으로 설치된 패키지를 삭제할 수 있습니다.

삭제 전 Proceed (Y/n)?으로 확인을 요청하며, -y 옵션을 추가하면 확인 없이 바로 삭제합니다.

PIP는 패키지를 삭제할 때 다른 패키지가 이 패키지를 사용하는지 확인하지 않습니다.

그러므로, Required-by에 다른 패키지가 있는 패키지를 삭제하면 그 패키지들이 import 단계에서 오류를 일으킬 수 있습니다. 삭제 전에 python -m pip show로 Required-by를 확인하고, 삭제 후에는 python -m pip check로 깨진 의존성이 없는지 확인합니다.

• Tip : 패키지를 삭제하더라도 함께 설치되었던 의존 패키지는 삭제되지 않습니다.

요구 사항 파일(requirements.txt)

프로젝트를 다른 컴퓨터로 옮기거나 다른 사람과 함께 작업하면, 같은 패키지를 같은 버전으로 다시 설치해야 합니다.

패키지를 하나씩 설치하면 빠뜨리거나 다른 버전을 설치하기 쉬우므로, 필요한 패키지 목록을 파일로 기록해 두고 한 번에 설치합니다.

python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt

python -m pip freeze는 설치된 패키지 목록을 패키지 이름==버전 형식으로 출력합니다.

출력 결과를 > 리다이렉션으로 requirements.txt 파일에 저장하면, 현재 환경의 패키지 목록을 기록할 수 있습니다.

python -m pip install -r requirements.txt를 사용하면 파일에 기록된 패키지들을 한 번에 설치할 수 있습니다.

다른 컴퓨터나 서버에서 동일한 패키지 환경을 재현할 때 사용합니다.

pip list와 pip freeze는 모두 설치된 패키지를 보여 주지만, 용도가 다릅니다.

pip list는 사람이 읽기 좋은 표 형식으로 출력하고, pip freeze는 install -r로 다시 설치할 수 있는 요구 사항 형식으로 출력합니다.

• Tip : conda 등 다른 도구로 설치한 패키지는 pip freeze에서 패키지 이름 @ file:///...처럼 로컬 경로로 출력될 수 있으며, 이 경로는 다른 컴퓨터에서 사용할 수 없습니다.

numpy==2.5.1
pandas>=2.0
requests

requirements.txt 파일은 직접 작성할 수도 있으며, 한 줄에 하나의 패키지를 작성합니다.

install 명령어와 동일하게 버전을 고정하거나, 범위를 지정하거나, 버전을 생략할 수 있습니다.

파일 안에서는 셸을 거치지 않으므로 >=를 따옴표로 감싸지 않습니다. #으로 시작하는 줄은 주석으로 처리됩니다.

pip freeze로 만든 파일에는 의존성으로 함께 설치된 패키지까지 모두 기록되므로, 직접 사용하는 패키지가 무엇인지 알아보기 어렵습니다.

직접 작성한 파일은 프로젝트가 직접 사용하는 패키지만 기록할 수 있어 관리하기 쉽지만, 의존 패키지의 버전은 설치 시점에 따라 달라질 수 있습니다.

• Tip : pip freeze는 해당 Python에 설치된 모든 패키지를 기록하므로, 프로젝트별로 가상 환경(venv)을 만들어 사용하는 것이 좋습니다.

외부 관리 환경 오류(externally-managed-environment)

error: externally-managed-environment

일부 리눅스 배포판이나 Homebrew로 설치한 macOS의 Python에서 pip install을 실행하면 위와 같은 오류가 발생할 수 있습니다.

이 오류는 PEP 668에 따라 운영체제의 패키지 관리자(apt, brew 등)가 관리하는 Python에 PIP로 패키지를 설치하지 못하도록 막는 것입니다.

시스템 Python에 패키지를 직접 설치하면 운영체제가 사용하는 패키지와 충돌할 수 있기 때문입니다.

예를 들어, 운영체제의 도구가 특정 버전의 패키지에 의존하고 있는데 PIP로 그 패키지를 업그레이드하면, 운영체제의 도구가 동작하지 않을 수 있습니다. 이는 앞에서 설명한 의존성 충돌이 운영체제 수준에서 일어나는 것입니다.

이 경우 가상 환경(venv)을 생성한 다음, 가상 환경 안에서 PIP로 패키지를 설치합니다.

가상 환경은 프로젝트마다 독립된 패키지 설치 공간을 제공하며, 자세한 사용법은 제 52강에서 다룹니다.

• Tip : --break-system-packages 옵션으로 이 제한을 무시할 수 있지만, 시스템 Python이 손상될 수 있으므로 권장하지 않습니다.

정리

PIP는 PyPI에 등록된 패키지를 현재 Python에 설치하는 도구이며, 패키지가 요구하는 의존성까지 함께 관리합니다.

패키지가 설치되는 위치는 PIP를 실행한 Python에 따라 결정되므로, python -m pip 형태로 어떤 Python에 설치하는지 명확히 하는 것이 가장 중요합니다.

프로젝트마다 가상 환경을 만들고, 필요한 패키지를 requirements.txt로 기록해 두면 다른 환경에서도 같은 패키지 구성을 쉽게 재현할 수 있습니다.