파이썬 requirements.txt 만들기 : pip freeze와 새 가상환경 설치

파이썬 코드를 다른 폴더나 PC로 옮겼는데, 전에 설치했던 패키지가 무엇인지 기억나지 않을 때가 있습니다. 이때 코드 파일과 함께 남겨 두는 것이 requirements.txt입니다. 패키지를 하나씩 다시 찾는 대신 이 파일을 읽어 설치할 수 있습니다.

여기서는 설치가 끝난 환경의 목록을 저장한 뒤, 비어 있는 두 번째 가상환경에 다시 설치하겠습니다. 설치 명령이 성공하는지뿐 아니라 두 환경의 패키지 이름과 버전이 같은지도 확인합니다.

확인일은 2026년 10월 6일입니다. Windows에서 Python 3.14 계열과 pip 26.2.1로 실습했고, 파일 저장 명령은 Windows PowerShell 5.1과 PowerShell 7에서 확인했습니다. 이 예제의 Requests 2.34.2는 Python 3.10 이상이 필요합니다.

패키지 목록을 기록하고 새 환경에 설치하는 개념 그림 (AI 제작)

requirements.txt는 설치 목록이지 환경 전체의 백업은 아닙니다

먼저 용어를 나누어 보겠습니다. 패키지는 설치해서 사용하는 파이썬 기능 묶음이고, pip는 패키지를 설치하고 관리하는 도구입니다. 가상환경은 프로젝트마다 설치 패키지를 따로 둘 수 있도록 만든 공간입니다.

requirements.txt는 pip에 전달할 설치 목록을 담은 텍스트 파일입니다. 예를 들어 requests==2.34.2라는 한 줄은 requests의 2.34.2 버전을 설치하라는 뜻입니다. ==로 이름과 정확한 버전을 연결합니다. 파일 이름은 관례이므로 다른 이름도 가능하지만, 처음에는 이 이름을 쓰면 알아보기 쉽습니다.

제목에 있는 pip freeze는 지정한 Python 환경에 설치된 패키지 목록을 requirements 형식으로 출력하는 명령입니다. 코드를 읽어서 필요한 패키지만 골라 주는 기능은 아닙니다. 출력만 할 때는 패키지를 설치하거나 삭제하지 않습니다.

전체 흐름은 세 단계입니다.

1. 첫 번째 가상환경에 예제 패키지를 설치합니다.
2. 그 환경의 pip freeze 출력으로 requirements.txt를 만듭니다.
3. 새 가상환경의 pip가 파일을 읽고 패키지를 설치합니다.

파일에는 Python 실행 파일이나 내 코드가 들어가지 않습니다. 다른 PC에서 사용할 때도 Python 설치와 코드 복사는 별도로 해야 합니다.

1. 빈 실습 폴더와 첫 번째 가상환경 준비하기

아래 명령은 파이썬의 >>> 입력창이 아니라 Windows PowerShell 터미널에 입력합니다. 먼저 python --version으로 사용할 Python을 확인합니다. --version은 설치나 변경 없이 버전만 출력하는 옵션입니다.

python --version

Python 3.10 이상인지 확인하고 진행합니다. python을 찾을 수 없거나 여러 버전 중 무엇이 실행되는지 모른다면 Python Install Manager 설치와 실행 방법부터 확인하시면 됩니다.

기존 프로젝트의 파일을 덮어쓰지 않도록 새 폴더에서 시작하겠습니다. 아래 이름의 폴더가 이미 있다면 다른 새 이름을 사용하세요. mkdir는 폴더 생성, cd는 작업 위치 이동 명령입니다.

mkdir requirements-demo
cd requirements-demo
python -m venv .venv

-m venv는 Python에 포함된 가상환경 생성 도구를 실행한다는 뜻입니다. 마지막의 .venv가 만들 폴더 이름입니다. 현재 python의 버전을 사용하는 가상환경이 생기며, 기존 Python 설치를 바꾸지는 않습니다.

이 글에서는 활성화 명령 대신 .venv 안의 Python을 직접 지정합니다. Scripts는 Windows 가상환경에서 실행 파일이 놓이는 폴더이고, 앞의 .\는 현재 폴더를 뜻합니다. 따라서 아래 명령은 첫 번째 가상환경의 pip로 Requests를 설치합니다.

.\.venv\Scripts\python.exe -m pip install requests==2.34.2

Requests는 웹 서버와 데이터를 주고받을 때 사용하는 패키지입니다. 여기서는 설치 목록을 만들어 볼 예제로만 사용하므로 별도 계정이나 API 키는 필요 없습니다. 설치 과정에서는 인터넷 연결이 필요하며, 성공하면 Successfully installed로 시작하는 결과가 표시됩니다.

2. pip freeze로 목록을 확인하고 UTF-8 파일로 저장하기

먼저 파일을 만들기 전에 화면으로 목록을 봅니다.

.\.venv\Scripts\python.exe -m pip freeze

테스트한 환경에서는 다음과 같이 다섯 줄이 나왔습니다.

certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
urllib3==2.8.0

Requests 하나를 지정했는데 다섯 개가 나오는 이유는 Requests가 다른 패키지의 기능도 사용하기 때문입니다. 이렇게 함께 필요한 패키지를 의존 패키지라고 합니다. pip가 설치 과정에서 함께 가져왔고, freeze는 이 패키지들도 기록합니다.

위 목록은 확인일의 실제 결과입니다. 나중에 실습하면 Requests가 요구하는 범위 안에서 다른 의존 패키지 버전이 설치될 수 있습니다. 위 다섯 줄을 외워서 옮기기보다, 본인이 만든 환경에서 나온 목록을 저장하면 됩니다.

저장은 다음과 같이 합니다. 같은 이름의 파일이 있으면 내용이 교체되므로 기존 프로젝트에서는 먼저 파일을 확인하거나 별도로 보관하세요.

.\.venv\Scripts\python.exe -m pip freeze | Set-Content -Encoding utf8 requirements.txt
Get-Content requirements.txt

|는 왼쪽 명령의 출력을 오른쪽 명령에 넘기는 기호입니다. Set-Content는 받은 내용을 파일에 쓰고, -Encoding utf8은 저장할 문자 인코딩을 UTF-8로 지정합니다. 두 번째 줄의 Get-Content는 저장된 파일 내용을 읽어 화면에 보여줍니다. 앞서 확인한 패키지 목록과 같은 내용인지 확인하세요.

웹에서 자주 보이는 pip freeze > requirements.txt도 출력 저장 명령입니다. 다만 Windows PowerShell 5.1의 >는 기본적으로 UTF-16LE 파일을 만들기 때문에, 여기서는 버전별 기본값에 기대지 않고 UTF-8을 명시했습니다. 테스트에서는 PowerShell 5.1의 UTF-8 파일과 PowerShell 7의 UTF-8 파일을 pip가 모두 읽었습니다. 참고로 UTF-16LE 파일도 이번 pip에서는 읽혔으므로, >를 쓰면 항상 설치가 실패한다고 이해할 필요는 없습니다.

목록이 비어 있거나 너무 길다면 먼저 실행 경로를 보세요. 새 가상환경에는 따로 설치한 패키지가 없어 freeze 결과가 비어 있을 수 있습니다. 반대로 여러 프로젝트가 섞인 기본 Python에서 실행하면 이 프로젝트와 관계없는 패키지까지 나옵니다. Python 3.12 이상에서는 기본 freeze 출력에서 pip 자체도 제외됩니다.

3. 두 번째 가상환경에 requirements.txt로 설치하기

같은 requirements-demo 폴더에서 이어서 진행합니다. .venv-check는 재설치를 확인할 새 가상환경 이름입니다. .venv를 복사하지 않고 같은 Python으로 새로 만듭니다.

python -m venv .venv-check
.\.venv-check\Scripts\python.exe -m pip freeze

이번 실습에서는 두 번째 줄에 패키지 목록이 나오지 않았습니다. 아직 Requests를 설치하지 않은 상태입니다. 그다음 저장해 둔 목록을 읽어 설치합니다.

.\.venv-check\Scripts\python.exe -m pip install -r requirements.txt

-r은 뒤에 적힌 파일에서 설치 요구사항을 읽게 하는 옵션입니다. 파일의 각 줄을 보고 해당 이름과 버전의 패키지를 설치합니다. requirements.txt를 패키지 이름으로 설치하는 것이 아니므로 -r을 빼지 않습니다.

새 환경에서 확인한 설치 완료 줄은 다음과 같았습니다.

Successfully installed certifi-2026.7.22 charset-normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0

동일한 패키지가 이미 설치되어 있으면 Requirement already satisfied가 표시될 수 있습니다. 오류가 아니라 해당 설치 요구사항을 이미 만족한다는 뜻입니다.

4. 설치 완료 뒤에는 목록과 import를 함께 확인하기

두 번째 환경에서 다시 목록을 출력합니다.

.\.venv-check\Scripts\python.exe -m pip freeze

실제 결과는 앞서 저장한 다섯 줄과 패키지 이름 및 버전이 모두 같았습니다. 이제 패키지를 코드에서 불러오는 것도 확인하겠습니다.

-c는 뒤의 문자열을 짧은 Python 코드로 실행하는 옵션입니다. import requests는 설치한 패키지를 불러오고, requests.__version__은 패키지가 제공하는 버전 문자열입니다. print(...)는 괄호 안의 값을 화면에 출력합니다. 한 줄의 두 문장은 ;로 구분했습니다.

.\.venv-check\Scripts\python.exe -c "import requests; print(requests.__version__)"
.\.venv-check\Scripts\python.exe -m pip check

출력은 순서대로 다음과 같았습니다.

2.34.2
No broken requirements found.

pip check는 설치된 패키지가 요구하는 의존 패키지와 버전 조건을 만족하는지 검사합니다. 위 결과는 이번 환경에서 그 검사를 통과했다는 뜻입니다. 내 프로그램 전체가 정상 동작한다는 보장은 아니므로, 실제 프로젝트에서는 여기서 끝내지 말고 사용하는 코드나 테스트도 실행해야 합니다.

파일을 공유하기 전에 구분할 세 가지

파일을 못 찾는 오류는 설치 버전 문제와 다릅니다

존재하지 않는 파일 이름을 -r 뒤에 지정했을 때 다음 오류를 확인했습니다.

ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'missing-requirements.txt'

이 경우 pip 업그레이드부터 할 필요는 없습니다. 현재 위치와 실제 파일 이름을 확인합니다. Get-Location은 작업 위치를 보여주고, Test-Path는 지정한 파일이나 폴더가 있는지 True 또는 False로 알려줍니다.

Get-Location
Test-Path .\requirements.txt

False라면 파일이 있는 폴더로 이동하거나 -r 뒤에 올바른 파일 경로를 적습니다. 경로에 공백이 있으면 따옴표로 감쌉니다. 메모장에서 직접 저장했다면 실제 이름이 requirements.txt.txt가 되지 않았는지도 확인하세요.

파일은 읽었지만 특정 패키지에서 설치가 멈춘다면 No matching distribution found의 패키지 이름과 Python 버전 확인 순서를 참고할 수 있습니다. 설치 성공 후 import만 실패한다면 ModuleNotFoundError와 실행 Python 경로 확인에서 설치 환경과 실행 환경을 맞춰 보세요.

-r은 목록 밖의 패키지를 지우지 않습니다

확인 실험으로 두 번째 환경에 sampleproject와 그 의존 패키지를 더 설치한 뒤 같은 requirements 파일을 다시 적용했습니다. 추가한 패키지는 그대로 남았습니다. 즉, pip install -r은 파일의 요구사항을 설치하는 명령이지 환경을 목록과 똑같이 정리하는 명령은 아닙니다.

제가 재설치 확인에 빈 가상환경을 쓰는 이유가 여기에 있습니다. 전에 설치한 패키지가 섞여 있으면 파일에 빠진 항목이 있어도 코드가 우연히 실행될 수 있습니다. 공유할 목록을 검증할 때는 새 환경에서 설치와 코드 실행을 함께 확인하는 편이 낫습니다.

버전 목록만으로 다른 PC까지 완전히 같아지지는 않습니다

pip freeze 출력은 설치된 상태를 기록한 것이며, 설치 파일의 해시까지 고정한 잠금 파일을 만드는 것은 아닙니다. Python 버전이나 운영체제가 달라지면 같은 패키지 버전을 설치할 수 없을 수 있습니다. 이번 실습도 같은 Windows와 같은 Python 버전에서 두 가상환경을 비교한 결과입니다.

또한 .venv 폴더에는 원래 위치를 가리키는 경로가 포함될 수 있어, 다른 위치로 통째로 복사해서 쓰기보다 그 위치에서 새로 만들어야 합니다. 전달할 때는 코드, 확인한 Python 버전, 설치 목록을 함께 남기세요.

마지막으로 파일을 직접 열어 이름==버전 이외의 줄이 있는지 살펴봅니다. 로컬 경로, 저장소 주소, 별도 설치 서버를 쓴 환경에서는 내 PC의 경로나 비공개 주소가 들어갈 수 있습니다. 인증 정보가 포함된 주소를 공개 저장소에 올리지 않도록 확인하고, 전달받은 파일도 출처와 내용을 확인한 뒤 설치하세요. requirements 파일은 패키지 설치를 지시하므로 단순 메모처럼 취급하면 안 됩니다.

참고한 공식 문서

• pip freeze : 설치 목록 출력과 기본 제외 항목
• pip requirements 파일 형식 : -r로 읽는 파일의 항목과 인코딩
• pip check : 설치된 의존 관계 검사
• Python venv : 가상환경 생성과 이동 시 주의점
• PowerShell 문자 인코딩 : 저장 명령의 기본값과 UTF-8 지정
• Requests 2.34.2 공식 배포 정보 : 예제 패키지와 지원 Python 버전

목록을 만든 뒤에는 새 환경에 설치하고 실제 코드를 한 번 실행해 보세요. 파일이 있다는 것과 그 파일만으로 프로젝트를 실행할 수 있다는 것은 다릅니다.