uv를 이용한 독립 실행형 Python 스크립트 만들기

• Python 스크립트에 uv를 활용해 의존성 설치 없이 즉시 실행 가능한 독립 실행형 스크립트를 만드는 방법
• Go 프로젝트에서 API 테스트용으로 Python 스크립트를 사용하는 상황에서 나온 실용적 접근법임

기존 방식의 한계

• httpx, IPython, loguru 등의 패키지를 사용하는 Python 스크립트를 실행하려면 다음 중 하나를 선택해야 했음
  • 시스템 Python에 직접 패키지 설치
  • 가상환경 생성 및 패키지 설치 후 실행
• 두 방법 모두 번거롭고, 시스템 환경에 영향을 줄 수 있으며, 타인에게 공유 시 설명이 길어지는 문제가 있음

uv로 간편한 스크립트 실행

• uv는 Python 패키지 관리자이자 pip 대체 도구로, 격리된 실행 환경에서 Python 스크립트를 실행 가능하게 해줌
• # /// script 주석을 통해 스크립트 내부에 의존성 정보를 명시할 수 있음

  # /// script  
  # dependencies = ["ipython", "httpx", "loguru"]  
  # ///  
  

• 위 설정이 포함된 스크립트는 다음 명령으로 실행 가능:

  uv run jam_users.py  
  

• uv는 자동으로 임시 가상환경 생성, 필요한 패키지 설치, 그리고 스크립트 실행까지 한 번에 처리함

실행 가능한 스크립트로 만들기

• 일반 Python 스크립트처럼 #!/usr/bin/env python을 이용해 실행 가능하게 만들 수 있지만, 이 방식은 uv의 script 주석을 인식하지 못함
• 대신 아래처럼 shebang에 uv 명령을 직접 넣어 해결할 수 있음

  #!/usr/bin/env -S uv run --script  
  # /// script  
  # dependencies = ["ipython", "httpx", "loguru"]  
  # ///  
  

• 이 방식은 chmod +x 후 직접 실행 가능하며, 다른 유닉스 시스템에서도 uv만 있으면 그대로 작동함:

  ./jam_users.py  
  

장점 및 활용도

• uv 방식은 다른 사람에게 스크립트를 전달할 때 매우 유용함
• 복잡한 사전 설정 없이도 필요한 패키지와 환경이 자동으로 세팅됨
• 시스템 Python이나 글로벌 환경을 오염시키지 않음
• 스크립트 하나로 실행과 의존성 관리가 모두 해결됨

필자는 과거에 다른 사람에게 Python 스크립트를 전달할 때 설치 설명이 복잡했던 경험이 있었지만, 이제는 uv를 통해 이 문제를 간단히 해결 가능하다고 설명함

• 작은 테스트 스크립트 뿐 아니라 실무용 자동화 스크립트에서도 효과적임