패키지 관리

1. 패키지 관리 소개

예를 들어, GitHub에 코드를 업로드 한다고 했을 때 가상환경까지 포함해서 업로드하진 않습니다. 그렇게 되면 너무나 많은 파일들이 업로드 되기 때문입니다. 뿐만 아니라 서버를 이전할 때에도 마찬가지입니다. 모든 환경을 파일로 전달하는 것은 비효율적입니다. 가상환경 폴더에는 내 컴퓨터의 경로까지 들어 있어 다른 컴퓨터에서는 그대로 쓸 수도 없습니다.

이러한 문제를 해결하기 위해 패키지 관리를 합니다. 설치할 패키지 목록만 전달하고, 받은 사람이 자기 컴퓨터에서 가상환경을 새로 만드는 방식입니다. 패키지 목록은 pip에 내장된 명령어로 관리할 수 있으며, 더 상세한 관리를 위해 별도의 패키지 관리 도구를 설치하여 사용할 수도 있습니다.

여기서는 pip freeze로 목록을 저장하고 pip install -r로 설치하는 pip의 기본 방법을 알아보겠습니다. 별도 도구인 uv는 이 절 맨 뒤의 참고 내용에서 다룹니다.

2. 패키지 파일 생성

가상환경 안에 패키지를 설치하였다면 requirements.txt 파일을 만들어 설치된 패키지 목록을 저장할 수 있습니다. pip freeze 명령어를 사용하면 설치된 패키지 목록을 출력할 수 있습니다.

5장에서 만든 05_blog 폴더로 이동하고 그 프로젝트의 가상환경을 활성화하세요. 새 가상환경을 만드는 것이 아니라 실습에 사용한 환경의 패키지 목록을 저장합니다.

.\venv\Scripts\Activate.ps1
pip freeze > requirements.txt

macOS/Linux에서는 source ./venv/bin/activate로 활성화합니다. Windows 명령 프롬프트에서는 venv\Scripts\activate.bat을 사용합니다.

이 명령어를 실행하면 가상환경 안에 설치된 패키지 목록이 프로젝트 최상위의 requirements.txt 파일에 저장됩니다. 파일을 열어 FastAPI, SQLAlchemy, PyJWT, pwdlib 등 설치한 패키지가 패키지명==버전 형식으로 기록되어 있는지 확인하세요. 직접 설치하지 않은 패키지도 다른 패키지가 필요로 해서 함께 설치되었다면 목록에 들어갑니다.

파일 인코딩 확인

Windows PowerShell의 버전에 따라 >로 저장한 파일이 UTF-16일 수 있습니다. VS Code에서 requirements.txt를 열고 오른쪽 아래 인코딩 표시를 클릭한 뒤 인코딩하여 저장 → UTF-8을 선택하세요. 다른 운영체제나 Docker에서도 읽을 수 있도록 UTF-8로 저장합니다.

패키지를 추가하거나 버전을 바꿨다면 실습이 정상 동작하는지 확인한 뒤 pip freeze > requirements.txt를 다시 실행하세요. pip은 이 파일을 자동으로 갱신하지 않습니다.

2.1 개발용 패키지 구분하기

7장에서 사용할 pytest 같은 도구는 개발할 때만 필요합니다. 개발 도구를 설치하기 전에 위의 requirements.txt를 저장해두고, requirements-dev.txt 파일을 따로 만듭니다.

-r requirements.txt
pytest
httpx2
pytest-cov

첫 줄은 실행에 필요한 패키지 목록도 함께 읽으라는 뜻입니다. 아래 명령은 실행용 패키지와 개발 도구를 모두 설치합니다.

pip install -r requirements-dev.txt

위 예시는 개발 도구의 버전을 지정하지 않았습니다. 팀에서 같은 버전을 사용하려면 설치 후 pip show pytest httpx2 pytest-cov로 확인한 버전을 각 이름 뒤에 ==버전 형식으로 적어주세요.

개발 도구를 설치한 환경에서 다시 pip freeze > requirements.txt를 실행하면 개발용 패키지까지 실행용 목록에 들어갑니다. 실행용 목록을 갱신할 때는 별도의 깨끗한 가상환경에서 기존 requirements.txt와 추가할 실행용 패키지만 설치한 뒤 저장하세요. 전체 개발 환경도 기록하고 싶다면 pip freeze > requirements-dev-lock.txt처럼 다른 파일에 저장할 수 있습니다.

3. gitignore 파일 생성

패키지 목록 파일을 만들었기 때문에 이제 가상환경을 업로드하지 않도록 해야 합니다. 이를 위해 .gitignore 파일을 만들어 가상환경을 업로드하지 않도록 합니다. 프로젝트 최상위에 .gitignore 파일을 생성하고 다음 내용을 입력합니다.

# 가상환경
venv/
.venv/

# 파이썬과 테스트 결과
__pycache__/
*.pyc
.pytest_cache/
.coverage
htmlcov/

# 데이터베이스와 비밀값
*.db
*.sqlite3
.env

# 업로드된 파일
uploads/

requirements.txt, requirements-dev.txt는 코드와 함께 Git에 올립니다. 가상환경, 실제 데이터, 비밀 키는 올리지 않습니다.

이미 커밋한 파일에는 적용되지 않습니다

.gitignore는 아직 추적하지 않는 파일에 적용됩니다. 이미 올라간 파일을 나중에 추가해도 계속 추적됩니다. 파일을 지우고 커밋하더라도 이전 기록에는 남으므로, 비밀 키를 실수로 올렸다면 그 키를 폐기하고 새로 발급해야 합니다.

4. 패키지 설치

GitHub에는 이제 가상환경이 함께 올라가지 않습니다. 따라서 GitHub에서 소스코드를 다운로드 받았다면 가상환경을 새로 만들고 목록대로 패키지를 설치해야 합니다.

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

macOS/Linux에서는 가상환경 생성에 python3 -m venv venv, 활성화에 source ./venv/bin/activate를 사용합니다.

이 명령어를 실행하면 requirements.txt 파일에 저장된 패키지가 설치됩니다. 설치 후 패키지 사이에 충돌이 없는지 확인하고 서버를 실행합니다.

pip check
fastapi dev main.py

6-5절처럼 파일을 나눈 뒤에는 fastapi dev app/main.py로 실행합니다. 테스트까지 실행할 환경이라면 pip install -r requirements-dev.txt도 실행하세요.

운영체제가 다르면 목록을 점검하세요

pip freeze는 현재 환경에 설치된 패키지 목록입니다. 파이썬 버전이나 운영체제가 다르면 설치할 수 없는 패키지가 있을 수 있습니다. 특히 Windows에서 만든 목록을 Linux Docker 이미지에 사용할 때는 새 환경에서 설치와 실행을 확인해야 합니다. 7장 배포 실습에서는 실행용 목록을 준비하고 컨테이너 안에서 버전을 기록하는 방법을 다룹니다.

5. 패키지 버전을 바꿀 때

현재 목록을 Git에 저장해둔 뒤 필요한 패키지만 업데이트합니다.

pip list
pip install --upgrade "fastapi[standard]"
pip check

서버와 주요 API가 동작하는지 확인하세요. 7장에서 테스트를 작성한 뒤에는 python -m pytest로 함께 확인합니다. 검증이 끝나면 2절에서 설명한 실행용·개발용 구분에 맞춰 패키지 목록을 갱신하고 코드와 함께 커밋하세요.

업그레이드 전 환경으로 돌아가려면 Git에 저장해둔 목록을 사용해 새 가상환경을 만듭니다. 기존 환경에 pip install -r만 실행하면 목록에 없는 패키지까지 삭제되지는 않습니다.

FastAPI 릴리스 노트

연습문제

5장 블로그의 가상환경을 활성화하고 requirements.txt를 만들어보세요.
pip show fastapi의 버전과 requirements.txt에 적힌 버전을 비교해보세요.
.gitignore를 작성하고 git status에 가상환경이 나타나지 않는지 확인해보세요.
새 폴더에 코드와 패키지 목록만 복사한 뒤, 새 가상환경에 pip install -r requirements.txt로 설치하고 실행해보세요.
requirements-dev.txt를 만들고 실행용과 개발용 패키지의 차이를 설명해보세요.

참고: uv로 패키지 관리하기

이 책은 설치 복잡도를 올리지 않기 위해 uv를 쓰지 않습니다. 파이썬에 들어 있는 venv와 pip만으로 마지막 장까지 실습할 수 있고, 도구를 하나 더 설치하고 익히는 데 드는 시간을 FastAPI 자체에 쓰는 편이 낫기 때문입니다.

다만 실무에서는 uv 사용을 권합니다. uv는 가상환경 생성, 패키지 설치, 설치한 버전을 고정하는 잠금 파일 관리를 한 도구로 처리하고, 설치 속도도 pip보다 훨씬 빠릅니다. 이 절에서 배운 pip freeze와 requirements.txt의 역할을 uv가 어떻게 대신하는지 알아두면, 실무 프로젝트에서 uv를 만났을 때 바로 적응할 수 있습니다. 이 부분은 선택 사항이며, 이후 실습과 배포는 계속 venv와 pip을 기준으로 진행합니다.

1. 설치와 별도 프로젝트 만들기

운영체제별 설치 방법은 공식 문서를 참고하세요.

uv 설치 문서

설치 후 새 터미널에서 uv --version으로 확인합니다. pip 실습 환경과 섞이지 않도록, 기존 가상환경이 켜져 있다면 deactivate로 빠져나온 뒤 실습 상위 폴더에서 별도 프로젝트를 만드세요.

mkdir uv_reference
cd uv_reference
uv init
uv add "fastapi[standard]"

생성된 main.py 내용을 1장의 첫 FastAPI 코드로 바꾼 뒤 실행합니다.

uv run fastapi dev main.py

uv는 .venv 가상환경을 관리하고, uv run은 그 환경에서 명령을 실행합니다. 직접 활성화하지 않아도 됩니다.

2. 기록되는 파일과 명령어

파일	내용
`pyproject.toml`	직접 추가한 패키지와 프로젝트 설정
`uv.lock`	의존성의 버전과 환경별 설치 정보

두 파일은 Git에 함께 올리고 .venv/는 .gitignore에 추가합니다. 다른 컴퓨터에서는 프로젝트 폴더에서 uv sync를 실행해 환경을 준비합니다.

작업	이 책의 기본 방식	uv 명령
패키지 설치	`pip install 패키지명`	`uv add 패키지명`
환경 준비	가상환경 생성·활성화 후 `pip install -r requirements.txt`	`uv sync`
서버 실행	`fastapi dev main.py`	`uv run fastapi dev main.py`
개발 도구 설치	`pip install -r requirements-dev.txt`	`uv add --dev pytest httpx2 pytest-cov`
테스트 실행	`python -m pytest`	`uv run python -m pytest`

pip 프로젝트의 기존 패키지 목록을 가져오려면 별도 복사본에서 uv init 후 uv add -r requirements.txt를 사용할 수 있습니다. 개발용 패키지는 별도로 추가하세요. pip freeze로 만든 목록에는 간접 의존성도 들어 있으므로 가져온 뒤 pyproject.toml을 점검합니다.

반대로 uv 프로젝트에서 pip용 목록을 내보낼 수도 있습니다.

uv export --no-dev --no-emit-project --format requirements-txt --output-file requirements.txt

이 명령은 uv 프로젝트가 이미 있을 때 사용합니다. 이 책의 pip 실습에서는 앞서 배운 pip freeze로 목록을 만들면 됩니다.