명령어 실행

프로젝트 작업 시 환경은 .venv에 설치되며 현재 셸에서 격리됩니다. 프로젝트 환경 내에서 명령어를 실행하려면 uv run을 사용합니다:

$ uv run python -c "import example"

명령어를 실행하기 전에, uv는 자동으로 프로젝트 환경이 최신 상태인지 확인합니다. 명령어 자체는 프로젝트 환경 또는 다른 곳에서 가져올 수 있습니다:

$ # 프로젝트가 `example-cli`를 제공한다고 가정
$ uv run example-cli foo

$ # 프로젝트를 사용할 수 있어야 하는 `bash` 스크립트 실행
$ uv run bash scripts/foo.sh

추가 의존성 요청

--with 옵션을 사용하여 실행 시마다 추가 의존성이나 대체 버전을 요청할 수 있습니다:

$ uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"
0.26.0
$ uv run --with httpx==0.25.0 python -c "import httpx; print(httpx.__version__)"
0.25.0

요청된 버전은 프로젝트 요구사항보다 우선합니다.

스크립트 실행

인라인 메타데이터가 있는 스크립트는 프로젝트와 별도의 격리된 환경에서 실행됩니다:

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

import httpx

resp = httpx.get("https://peps.python.org/api/peps.json")
data = resp.json()
print([(k, v["title"]) for k, v in data.items()][:10])

uv run example.py를 실행하면 프로젝트에서 격리되어 선언된 의존성만으로 실행됩니다.

Windows의 레거시 스크립트

.venv\Scripts에 설치된 레거시 setuptools 스크립트를 지원합니다. 현재 .ps1, .cmd, .bat 확장자를 지원합니다:

$ uv run --with nuitka==2.6.7 -- nuitka.cmd --version

확장자를 생략할 수 있습니다. uv가 자동으로 일치하는 파일을 검색합니다:

$ uv run --with nuitka==2.6.7 -- nuitka --version

시그널 처리(Signal handling)

uv는 오류 보고 개선을 위해 프로세스 제어를 유지하며, 시그널을 자식 프로세스에 전달합니다.

Unix 시스템에서 uv는 대부분의 시그널을 전달합니다(SIGKILL, SIGCHLD, SIGIO, SIGPOLL 제외). SIGINT 전달은 여러 번 전송된 경우 또는 자식 프로세스 그룹이 uv와 다를 때만 발생합니다.

Windows에서 uv는 Ctrl-C 이벤트를 무시하여 자식 프로세스가 정상적으로 종료를 처리할 수 있도록 합니다.

원문(영어): https://docs.astral.sh/uv/concepts/projects/run/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/concepts/projects/run/