Uv: 의존성이 있는 스크립트 실행하기

• uv를 사용하면 Python 스크립트 실행 시 의존성 관리를 자동화함
• 별도의 가상환경 관리 없이 스크립트별로 환경이 자동으로 생성 및 유지됨
• 필요한 패키지는 inline metadata 또는 명령행 옵션 등 다양한 방식으로 선언 가능함
• Python 버전과 패키지 관리도 스크립트 단위로 선언 및 자동 조정 가능함
• Lock 파일과 의존성 버전 제한 옵션 등으로 재현성과 유지관리성을 높임

개요

• uv는 Python 스크립트 실행 시 해당 스크립트가 필요로 하는 패키지 의존성을 자동으로 관리해주는 도구임
• 사용자는 번거로운 가상환경 생성, 패키지 설치를 직접 하지 않아도 됨
• 여러 실행 옵션과 inline metadata 활용법, 다양한 의존성 선언 방식, 각종 제어 기능을 제공함

Python 환경과 uv의 역할

• Python은 각각의 설치마다 고유한 환경을 가짐
• 일반적으로 가상환경을 만들고 관리하는 것이 권장됨
• uv는 가상환경을 자동으로 관리하며, 선언적 방식으로 의존성을 다룸
• 단순한 스크립트는 uv run example.py만으로 즉시 실행 가능함
• 표준 라이브러리 사용 시 추가 설정 없이 작동함

인자 전달 및 입력 방식

• 스크립트에 명령행 인자를 넘길 수 있음
• 표준 입력에서 직접 스크립트 코드를 받아 실행하거나, here-document 기능도 지원함

프로젝트 환경과 --no-project 옵션

• 스크립트가 프로젝트 폴더(예: pyproject.toml이 있는 곳)에서 실행될 경우, 프로젝트 의존성도 설치됨
• 필요 없다면 --no-project 플래그를 스크립트 이름 앞에 넣어 프로젝트 환경을 무시할 수 있음

스크립트 의존성 선언과 관리

• 외부 패키지가 필요한 경우, 명령행 옵션 --with를 이용해 의존성을 지정해서 실행 가능함
• 특정 버전 제약 조건도 지원하며, 여러 의존성도 반복해서 옵션으로 지정 가능함
• 프로젝트 환경에서 추가 의존성을 더할 수 있고, 원하지 않으면 --no-project로 제어 가능함

Inline Script Metadata(PEP 723 방식)

• Python에서는 이제 스크립트 자체에 의존성이나 Python 버전을 선언하는 표준 포맷을 지원함
• uv init --script로 인라인 메타데이터가 포함된 스크립트를 손쉽게 생성 가능함
• uv add --script로 스크립트에 필요한 의존성을 TOML 포맷으로 추가 관리할 수 있음
• 인라인 메타데이터가 있으면, 프로젝트의 의존성은 무시되고 오직 스크립트 의존성만 적용됨

Python 버전 선언 및 관리

• 스크립트 내 또는 실행 시 원하는 Python 버전을 지정할 수 있음
• 지정된 버전이 없다면 자동으로 다운로드 및 설정됨

Shebang으로 바로 실행 가능한 스크립트 작성

• shebang(@#!...)을 이용해 uv run --script 방식으로 직접 실행 파일 제작 가능함
• 이때도 의존성 선언 및 Python 버전 등도 스크립트 상단에서 가능함

패키지 인덱스 및 인증 지원

• --index 옵션으로 커스텀 패키지 인덱스 사용 가능
• index 정보도 메타데이터에 포함됨
• 인증이 필요한 경우 별도 문서 참고 가능

의존성 고정(Lock)과 재현성 향상

• uv lock --script로 스크립트 단위의 Lock 파일 작성 및 관리 가능
• 이후 실행/의존성 추가 시 lock 파일 재사용 및 필요시 갱신됨
• 버전 재현성을 위한 exclude-newer(특정 날짜 이후 릴리즈 제외) 옵션 제공
• RFC 3339 타임스탬프로 날짜 지정

Python 버전 유연성

• 각 실행 시 명령행 옵션으로 任의의 Python 버전 사용 지정 가능
• 예시: uv run --python 3.10 example.py

Windows 지원

• .pyw 확장자를 가진 스크립트는 윈도우에서 pythonw로 실행됨
• GUI 기반의 스크립트도 의존성 함께 실행 가능함

참고 문서

• 더 자세한 명령 사용법은 CLI 참조 문서 및 툴 실행/설치 가이드 참고 가능

결론

• uv는 Python 스크립트의 실행 환경, 의존성, 버전, 패키지 인덱스, 재현성 등을 자동으로 간편하게 관리해 생산성과 신뢰성을 동시에 높여주는 도구임