파이썬 프로젝트 README, 설치·실행·검증 명령까지 한 번에 정리하기
README를 읽는 사람은 대개 세 가지부터 궁금해해요. 무엇을 설치해야 하는지, 어떤 명령으로 프로그램을 시작하는지, 지금 정상적으로 동작하는지 어떻게 확인하는지입니다. 프로젝트 설명이 아무리 좋아도 이 답을 찾기 어렵다면 첫 실행 전에 막히기 쉽죠. 반대로 명령을 복사해 차례대로 실행할 수 있게 구성하면 작은 개인 프로젝트도 훨씬 다루기 편해집니다. 아래에서는 가상의 weather_cli 프로젝트를 예로 들어 README의 명령 구역을 정리해 볼게요.
명령보다 먼저 실행 조건을 고정해요
설치 명령 바로 위에는 지원하는 Python 버전과 명령을 실행할 위치를 적어 주세요. 예를 들어 “Python 3.12 이상이 필요하며, 다음 명령은 pyproject.toml이 있는 저장소 최상위 디렉터리에서 실행합니다”처럼 쓰면 됩니다. 운영체제나 셸에 따라 명령이 달라진다면 그 조건도 함께 표시해야 해요.
가상 환경 이름은 README 전체에서 하나로 통일하는 편이 좋습니다. 공식 Python 문서에 따르면 python -m venv .venv로 환경을 만들 수 있고, bash나 zsh에서는 source .venv/bin/activate로 활성화합니다. Windows PowerShell에서는 .venv\Scripts\Activate.ps1을 사용해요. 활성화가 필수는 아니지만, 프로젝트별 의존성을 분리하기 위한 이해하기 쉬운 안내가 됩니다.
여기서 python과 python3을 문단마다 섞으면 독자가 서로 다른 인터프리터를 사용할 수 있어요. README에서는 프로젝트가 기준으로 삼는 표기 하나를 택하고, “환경에 따라 python3 또는 Windows의 py를 사용해야 할 수 있습니다”라는 짧은 메모를 붙이는 방식을 권해요. 설치 전 python --version과 python -m pip --version을 확인하도록 적어 두면 인터프리터와 pip가 준비됐는지도 바로 점검할 수 있습니다.
설치는 프로젝트 파일에 맞춰 한 갈래로 보여 주세요
의존성 파일이 여러 개 있다고 해서 모든 설치법을 첫 화면에 늘어놓을 필요는 없어요. pyproject.toml을 사용하는 패키지라면 기본 예시는 python -m pip install .로 둘 수 있습니다. 코드를 수정하면서 실행해야 하는 개발자용 저장소라면 python -m pip install --editable .을 안내할 수 있어요. editable 설치는 소스 변경을 다시 설치하지 않고 반영하는 개발 방식이라는 점도 한 줄 덧붙이면 좋습니다.
개발 의존성을 dev extra로 정의한 프로젝트라면 python -m pip install --editable ".[dev]"처럼 실제 설정과 일치하는 명령을 적어 주세요. dev extra가 없는데 관습만 보고 이 명령을 넣으면 설치 단계부터 실패합니다. requirements.txt를 사용하는 프로젝트라면 대신 python -m pip install -r requirements.txt를 제시하면 돼요. 둘을 모두 지원한다면 “일반 사용자”와 “기여자”로 목적을 나눠 설명하세요.
설치 구역은 다음처럼 읽히면 충분합니다. “가상 환경 생성 → 활성화 → 패키지 설치”의 세 단계예요. pip 대신 python -m pip 형태를 쓰면 현재 선택한 Python 인터프리터를 통해 pip를 호출한다는 관계도 더 분명하게 드러납니다. 명령 뒤에는 정상 완료의 기준을 짧게 적어 주세요. 예를 들면 “오류 없이 설치가 끝나면 다음 실행 단계로 이동합니다” 정도면 됩니다.
실행 명령에는 입력과 결과의 모양을 붙여요
“실행하세요”라는 설명보다 실제 시작점 하나를 보여 주는 것이 낫습니다. 패키지가 모듈 실행을 지원한다는 가정의 예시는 python -m weather_cli --city Seoul입니다. Python의 -m 옵션은 지정한 모듈을 표준 import 방식으로 찾아 스크립트처럼 실행합니다. 다만 이 명령은 해당 패키지에 실행 가능한 모듈 구성이 있을 때만 쓸 수 있으니, README를 작성할 때 실제로 동작하는지 확인해야 해요.
pyproject.toml의 [project.scripts]에 weather-cli = "weather_cli.cli:main" 같은 콘솔 명령을 선언했다면 설치 후 weather-cli --city Seoul처럼 안내할 수도 있습니다. 패키징 명세상 [project.scripts]는 콘솔 스크립트 진입점을 정의하는 표예요. 선언하지 않은 명령을 README에만 적어 놓아서는 실행 파일이 생기지 않습니다.
예시 입력에는 독자가 바꿔야 할 값도 표시해 주세요. “Seoul을 원하는 도시 이름으로 바꿉니다”처럼 구체적으로 쓰고, 성공하면 어떤 형태의 출력이 나오는지도 한두 줄로 설명합니다. 실제 출력이 환경이나 외부 데이터에 따라 달라진다면 고정된 숫자를 약속하지 말고 “도시 이름과 결과 요약이 표시됩니다”처럼 구조만 알려 주는 편이 정확해요. 필수 환경 변수가 있다면 실행 명령 앞에 변수 이름, 용도, 예시용 더미 값을 적되 실제 비밀 키는 절대 넣지 않습니다.
검증 명령은 실행과 별도의 계약이에요
프로그램이 켜지는 것과 프로젝트가 검증을 통과하는 것은 다른 문제예요. pytest를 사용하는 프로젝트라면 검증 구역에 python -m pytest를 기본 명령으로 둘 수 있습니다. pytest 공식 문서에 따르면 이 명령은 기본 탐색 규칙에 맞는 테스트를 찾아 실행합니다. 종료 코드 0은 수집된 테스트가 모두 통과했다는 뜻이며, 테스트 실패나 수집 실패는 별도로 구분됩니다.
전체 테스트가 오래 걸리거나 특정 기능만 확인할 필요가 있다면 범위를 줄인 명령도 함께 적어 주세요. 예를 들어 python -m pytest tests/test_cli.py는 파일 하나를, python -m pytest tests/test_cli.py::test_city_argument는 특정 테스트를 대상으로 합니다. 다만 tests 경로와 함수 이름은 저장소에 실제로 존재하는 값이어야 합니다.
정적 분석기, 포매터, 타입 검사기를 사용한다면 각 도구의 실제 설정에 맞는 명령을 “추가 검사”로 분리하는 것을 권해요. 설치되지 않은 도구를 검증 단계에 갑자기 등장시키지 말고, 개발 의존성 설치 명령과 연결해야 합니다. 마지막에는 “전체 검증: python -m pytest”처럼 CI에서 실행하는 핵심 명령을 하나로 다시 보여 주면 기여자가 같은 기준을 재현하기 쉬워져요.
깨끗한 환경에서 README 자체를 시험해요
README 명령은 코드와 함께 관리되는 실행 절차입니다. 작성이 끝나면 기존 가상 환경이나 전역 패키지에 기대지 않는 상태에서 위에서 아래로 실행해 보세요. 새로 받은 저장소라는 가정으로 Python 버전을 확인하고, .venv를 만들고, 의존성을 설치한 뒤, 예제 실행과 전체 테스트까지 이어 가면 됩니다.
확인할 항목은 단순해요. 명령을 실행하는 디렉터리가 명확한가, macOS·Linux와 Windows의 차이가 표시됐는가, 예시 모듈과 테스트 경로가 실제 파일명과 같은가, 설치하지 않은 도구가 중간에 등장하지 않는가를 봅니다. 셸 프롬프트의 $나 >를 코드와 함께 복사해야 하는 문자처럼 넣지 않는 것도 중요해요.
프로젝트의 명령이 바뀌면 README와 자동화 설정도 함께 고쳐야 합니다. 가능하다면 README의 검증 명령과 CI의 테스트 명령을 동일하게 유지하세요. 문서 전용 축약 명령을 새로 만들기보다는 저장소에서 계속 실행되는 명령을 그대로 노출하는 편이 관리하기 쉽습니다. 빠른 시작 구역에는 최소 경로만 남기고, 옵션 설명과 문제 해결은 뒤쪽으로 보내면 처음 온 사람과 기여자 모두 필요한 깊이만 골라 읽을 수 있어요.
좋은 README는 명령을 많이 모아 둔 문서가 아니라, 준비에서 확인까지 끊기지 않는 경로를 제공하는 문서예요. 실행 조건을 밝히고, 설치 방식을 하나로 정하고, 실제 진입점과 예시 입력을 보여 준 다음, 테스트 통과 기준으로 마무리해 보세요. 마지막으로 깨끗한 환경에서 그대로 복사해 실행해 보면 빠진 전제와 오래된 경로가 눈에 들어옵니다. 이 정도만 지켜도 “그래서 뭘 입력해야 하죠?”라는 질문을 상당 부분 README 안에서 해결할 수 있습니다.