- 작은 API 테스트 스크립트도 의존성 때문에 실행 환경을 맞춰야 하는데, uv 실행 shebang을 쓰면 설치 절차 없이 바로 실행 가능한 형태로 만들 수 있음
- 예시
jam_users.py는 Go API의 /users 엔드포인트를 테스트하기 위해 httpx, IPython, loguru로 사용자 삭제·생성 후 REPL에 진입함
- 기존 방식은 시스템 Python에 패키지를 전역 설치하거나 가상환경을 직접 준비해야 해, 스크립트 공유와 재실행이 번거로움
# /// script 헤더에 dependencies = ["ipython", "httpx", "loguru"]를 선언하고 uv run jam_users.py를 실행하면 uv가 격리 환경과 의존성 설치를 처리함#!/usr/bin/env -S uv run --script shebang과 실행 권한을 더하면, Unix 시스템에서 uv만 설치된 상태로 ./jam_users.py처럼 실행할 수 있음
스크립트 안에 의존성 선언하기
- 예시
jam_users.py는 로컬 API http://localhost:4000/v1/users를 대상으로 테스트 사용자 데이터를 준비함
- httpx로 API 요청을 보냄
- IPython REPL에 진입해 응답을 살펴보고 테스트를 이어감
loguru로 삭제 및 생성 로그를 남김
- 기본 스크립트는 사용자 목록을 초기화한 뒤 테스트 데이터를 다시 채우는 흐름임
GET /v1/users로 기존 사용자 목록을 가져옴- 각 사용자에 대해
DELETE /v1/users/{id}를 호출함
- 준비된 사용자 목록을
POST /v1/users에 JSON으로 전송함
- 이후
IPython.embed()로 REPL을 띄움
python jam_users.py로 실행하려면 httpx, IPython, loguru가 실행 환경에 이미 설치되어 있어야 함- 시스템 Python에 전역 설치하거나 가상환경을 따로 만드는 방법도 있지만, 둘 다 실행 전 준비가 필요함
- 전역 설치는 시스템 Python을 패키지로 어지럽힐 수 있음
- 가상환경 방식은 생성, 활성화, 설치, 실행 과정을 직접 관리해야 함
- 두 방식 모두 필요한 패키지와 호환되는 시스템 Python이 있어야 함
uv로 직접 실행 가능한 스크립트 만들기
- uv의
# /// script 태그를 스크립트 상단에 넣으면 파일 안에서 의존성을 선언할 수 있음
# /// script
# dependencies = ["ipython", "httpx", "loguru"]
# ///
- 이 헤더가 있으면
uv run jam_users.py로 실행할 수 있음
- uv가 스크립트용 격리 가상환경을 생성함
- 필요한 의존성을 다운로드하고 설치함
- 해당 가상환경 맥락에서 스크립트를 실행함
- 일반 Python shebang인
#!/usr/bin/env python은 Python이 # /// script 주석을 무시하므로 uv의 스크립트 헤더를 활용하지 못함
- shebang에 uv 호출을 직접 넣으면 스크립트를 실행 파일처럼 다룰 수 있음
#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["ipython", "httpx", "loguru"]
# ///
env의 -S 플래그는 뒤따르는 문자열을 별도 인자로 나눠 env에 전달하도록 함chmod +x jam_users.py로 실행 권한을 부여한 뒤에는 다음처럼 직접 실행 가능함
./jam_users.py
- 이 방식은 Unix 시스템에 uv가 설치되어 있으면 별도의 의존성 설치나 가상환경 관리 없이 스크립트를 실행할 수 있음
- 복잡한 Python 스크립트를 다른 사용자에게 전달할 때, 실행 전 시스템 준비 절차를 길게 안내해야 하는 부담을 줄일 수 있음