도구¶

도구는 커맨드라인 인터페이스를 제공하는 파이썬 패키지이다.

Note

도구 인터페이스 작업에 대한 소개는 도구 가이드를 참고한다. 이 문서에서는 도구 관리의 세부 사항에 대해 다룬다.

`uv tool` 인터페이스¶

uv는 도구와 상호작용하기 위한 전용 인터페이스를 제공한다. uv tool run을 사용하면 도구를 설치하지 않고도 실행할 수 있다. 이 경우 도구의 의존성은 현재 프로젝트와 격리된 임시 가상 환경에 설치된다.

도구를 설치하지 않고 실행하는 경우가 매우 흔하기 때문에, uv tool run에 대한 별칭으로 uvx를 제공한다. 두 커맨드는 완전히 동일하다. 간결함을 위해, 문서에서는 주로 uv tool run 대신 uvx를 사용할 것이다.

도구는 uv tool install로 설치할 수도 있다. 이 경우 실행 파일이 PATH에서 사용 가능해진다. 여전히 격리된 가상 환경이 사용되지만, 커맨드가 완료된 후에도 제거되지 않는다.

실행 vs 설치¶

대부분의 경우, uvx로 도구를 실행하는 것이 설치하는 것보다 더 적합하다. 도구를 설치하는 것은 시스템의 다른 프로그램에서도 해당 도구를 사용해야 할 때 유용하다. 예를 들어, 여러분이 제어할 수 없는 스크립트가 해당 도구를 필요로 하거나, Docker 이미지 내에서 사용자에게 도구를 제공하려는 경우에 해당한다.

도구 환경 설정¶

uvx로 도구를 실행할 때, 가상 환경은 uv 캐시 디렉토리에 저장되며 일회성으로 처리된다. 즉, uv cache clean을 실행하면 해당 환경이 삭제된다. 이 환경은 반복 실행 시 발생하는 오버헤드를 줄이기 위해 캐시로만 사용된다. 환경이 삭제되면 자동으로 새로운 환경이 생성된다.

uv tool install로 도구를 설치할 때는 uv 도구 디렉토리에 가상 환경이 생성된다. 이 환경은 도구를 제거하지 않는 한 삭제되지 않는다. 환경을 수동으로 삭제하면 도구 실행이 실패한다.

도구 버전 관리¶

특정 버전을 요청하지 않으면, uv tool install은 요청한 도구의 최신 버전을 설치한다. uvx는 첫 실행 시 요청한 도구의 최신 버전을 사용한다. 이후에는 다른 버전을 요청하거나 캐시를 정리하거나 갱신하지 않는 한, uvx는 캐시된 버전을 사용한다.

예를 들어, 특정 버전의 Ruff를 실행하려면:

$ uvx ruff@0.6.0 --version
ruff 0.6.0

이후 uvx를 호출하면 캐시된 버전이 아닌 최신 버전을 사용한다.

$ uvx ruff --version
ruff 0.6.2

하지만 Ruff의 새 버전이 출시되더라도 캐시를 갱신하지 않으면 사용되지 않는다.

최신 버전의 Ruff를 요청하고 캐시를 갱신하려면 @latest 접미사를 사용한다:

$ uvx ruff@latest --version
0.6.2

uv tool install로 도구를 설치하면, uvx는 기본적으로 설치된 버전을 사용한다.

예를 들어, 이전 버전의 Ruff를 설치한 후:

$ uv tool install ruff==0.5.0

ruff와 uvx ruff의 버전은 동일하다:

$ ruff --version
ruff 0.5.0
$ uvx ruff --version
ruff 0.5.0

하지만 최신 버전을 명시적으로 요청하면 설치된 버전을 무시할 수 있다:

$ uvx ruff@latest --version
0.6.2

또는 --isolated 플래그를 사용하면 캐시를 갱신하지 않고 설치된 버전을 무시한다:

$ uvx --isolated ruff --version
0.6.2

uv tool install도 {package}@{version} 및 {package}@latest 지정자를 지원한다:

$ uv tool install ruff@latest
$ uv tool install ruff@0.6.0

도구 디렉토리¶

기본적으로 uv 도구 디렉토리는 tools라는 이름으로 지정되며, uv 애플리케이션 상태 디렉토리 내에 위치한다. 예를 들어, ~/.local/share/uv/tools와 같은 경로다. 이 위치는 UV_TOOL_DIR 환경 변수를 사용해 커스터마이징할 수 있다.

도구 설치 디렉토리의 경로를 표시하려면 다음 명령어를 실행한다:

$ uv tool dir

도구 환경은 도구 패키지와 동일한 이름의 디렉토리에 위치한다. 예를 들어, .../tools/<name>과 같은 경로다.

툴 환경 변경하기¶

툴 환경을 직접 변경하는 것은 권장하지 않는다. 특히 pip 명령어로 수동으로 변경하는 것은 절대 피해야 한다.

툴 환경은 uv tool upgrade 명령어로 업그레이드하거나, 이후 uv tool install 명령어로 완전히 재생성할 수 있다.

툴 환경의 모든 패키지를 업그레이드하려면:

$ uv tool upgrade black

툴 환경의 특정 패키지를 업그레이드하려면:

$ uv tool upgrade black --upgrade-package click

툴 환경의 모든 패키지를 재설치하려면:

$ uv tool upgrade black --reinstall

툴 환경의 특정 패키지를 재설치하려면:

$ uv tool upgrade black --reinstall-package click

툴 업그레이드는 툴 설치 시 제공한 버전 제약 조건을 준수한다. 예를 들어, uv tool install black >=23,<24를 실행한 후 uv tool upgrade black을 실행하면 Black을 >=23,<24 범위 내의 최신 버전으로 업그레이드한다.

버전 제약 조건을 대체하려면 uv tool install로 툴을 재설치한다:

$ uv tool install black>=24

마찬가지로, 툴 업그레이드는 툴 설치 시 제공한 설정을 유지한다. 예를 들어, uv tool install black --prerelease allow를 실행한 후 uv tool upgrade black을 실행하면 --prerelease allow 설정이 유지된다.

툴 업그레이드는 툴 실행 파일이 변경되지 않았더라도 재설치한다.

추가 의존성 포함하기¶

도구 실행 시 추가 패키지를 포함할 수 있다:

$ uvx --with <extra-package> <tool>

또한, 도구 설치 시에도 추가 패키지를 포함할 수 있다:

$ uv tool install --with <extra-package> <tool-package>

--with 옵션은 여러 번 제공할 수 있어 추가 패키지를 여러 개 포함할 수 있다.

--with 옵션은 패키지 명세를 지원하므로 특정 버전을 요청할 수 있다:

$ uvx --with <extra-package>==<version> <tool-package>

요청한 버전이 도구 패키지의 요구 사항과 충돌하면 패키지 해결이 실패하고 명령어가 오류를 발생시킨다.

툴 실행 파일¶

툴 실행 파일은 Python 패키지가 제공하는 모든 콘솔 진입점, 스크립트 진입점, 바이너리 스크립트를 포함한다. Unix 시스템에서는 툴 실행 파일이 bin 디렉토리에 심볼릭 링크로 연결되고, Windows에서는 복사된다.

`bin` 디렉토리¶

실행 파일은 XDG 표준에 따라 사용자의 bin 디렉토리에 설치된다. 예를 들어 ~/.local/bin과 같은 경로다. uv의 다른 디렉토리 구조와 달리, XDG 표준은 Windows와 macOS를 포함한 모든 플랫폼에서 사용된다. 특히 이 플랫폼들에서는 실행 파일을 배치할 명확한 대체 위치가 없기 때문이다. 설치 디렉토리는 다음 환경 변수 중 첫 번째로 사용 가능한 값으로 결정된다:

$UV_TOOL_BIN_DIR
$XDG_BIN_HOME
$XDG_DATA_HOME/../bin
$HOME/.local/bin

도구 패키지의 의존성에서 제공하는 실행 파일은 설치되지 않는다.

`PATH` 변수¶

툴 실행 파일을 셸에서 사용하려면 bin 디렉터리가 PATH 변수에 포함되어야 한다. PATH에 포함되지 않으면 경고 메시지가 표시된다. uv tool update-shell 커맨드를 사용하면 일반적인 셸 설정 파일에 bin 디렉터리를 PATH에 추가할 수 있다.

실행 파일 덮어쓰기¶

도구를 설치할 때, UV가 이전에 설치하지 않은 bin 디렉토리의 실행 파일은 덮어쓰지 않는다. 예를 들어, pipx를 사용해 도구를 설치한 경우, uv tool install 명령어는 실패한다. 이 동작을 무시하려면 --force 플래그를 사용한다.

`uv run`과의 관계¶

uv tool run <name> 명령(또는 uvx <name>)은 다음 명령과 거의 동일하다:

$ uv run --no-project --with <name> -- <name>

하지만 uv의 도구 인터페이스를 사용할 때 몇 가지 주목할 만한 차이점이 있다:

--with 옵션이 필요하지 않다. 명령어 이름에서 필요한 패키지를 자동으로 추론한다.
임시 환경이 전용 위치에 캐시된다.
--no-project 플래그가 필요하지 않다. 도구는 항상 프로젝트와 격리된 상태로 실행된다.
도구가 이미 설치되어 있다면, uv tool run은 설치된 버전을 사용하지만 uv run은 사용하지 않는다.

도구를 프로젝트와 격리하지 않고 실행해야 하는 경우(예: pytest나 mypy를 실행할 때)에는 uv tool run 대신 uv run을 사용해야 한다.

도구¶

uv tool 인터페이스¶