CPN 한국어 자습서 · 외부 문서 한국어 미러
UV 문서 · Concepts
Tools · 원문: docs.astral.sh/uv/concepts/tools/
아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.
도구(tool)는 명령줄 인터페이스를 제공하는 Python 패키지입니다.
uv tool 인터페이스uv는 도구와 상호작용하기 위한 전용 인터페이스를 제공합니다. 도구는 uv tool run을 사용하여 설치 없이 실행할 수 있으며, 이 경우 의존성은 현재 프로젝트와 격리된 임시 가상환경에 설치됩니다.
도구를 설치하지 않고 실행하는 경우가 매우 흔하기 때문에, uv tool run의 별칭으로 uvx가 제공됩니다. 두 명령은 완전히 동일합니다. 간결성을 위해 이 문서에서는 uv tool run 대신 uvx를 주로 사용합니다.
도구는 uv tool install로 설치할 수도 있으며, 이 경우 실행 파일이 PATH에서 사용 가능해집니다. 이때도 격리된 가상환경이 사용되지만, 명령 완료 후에도 제거되지 않습니다.
대부분의 경우, 도구를 설치하는 것보다 uvx로 실행하는 편이 더 적합합니다. 도구를 설치하는 것은 시스템의 다른 프로그램에서 해당 도구가 필요할 때 유용합니다. 예를 들어, 직접 제어할 수 없는 스크립트가 도구를 필요로 하거나, Docker 이미지 안에서 사용자에게 도구를 제공하고자 할 때입니다.
uvx로 도구를 실행하면 가상환경은 uv 캐시 디렉터리에 저장되며 일회용으로 취급됩니다. 즉, uv cache clean을 실행하면 환경이 삭제됩니다. 환경은 반복 호출의 오버헤드를 줄이기 위해서만 캐시됩니다. 환경이 삭제되면 자동으로 새로 생성됩니다.
uv tool install로 도구를 설치하면 가상환경은 uv 도구 디렉터리에 생성됩니다. 도구를 제거하지 않는 한 환경은 삭제되지 않습니다. 환경을 수동으로 삭제하면 도구가 실행되지 않습니다.
중요: 도구 환경은 직접 수정하도록 설계되지 않았습니다.
pip작업 등으로 도구 환경을 수동으로 수정하지 않을 것을 강력히 권장합니다.
특정 버전을 지정하지 않으면 uv tool install은 요청한 도구의 최신 버전을 설치합니다. uvx는 첫 번째 호출 시 요청한 도구의 최신 버전을 사용합니다. 이후에는 다른 버전이 요청되거나 캐시가 정리 또는 갱신되지 않는 한 캐시된 버전을 사용합니다.
예를 들어, 특정 버전의 Ruff를 실행하려면:
$ uvx [email protected] --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 [email protected]
도구 환경은 uv tool upgrade로 업그레이드하거나, 이후 uv tool install 작업으로 완전히 재생성할 수 있습니다.
도구 환경의 모든 패키지를 업그레이드하려면:
$ uv tool upgrade black
도구 환경의 특정 패키지를 업그레이드하려면:
$ uv tool upgrade black --upgrade-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 설정이 유지됩니다.
참고: 도구 업그레이드는 변경되지 않은 경우에도 도구 실행 파일을 재설치합니다.
업그레이드 시 패키지를 재설치하려면 --reinstall 및 --reinstall-package 옵션을 사용합니다.
도구 환경의 모든 패키지를 재설치하려면:
$ uv tool upgrade black --reinstall
도구 환경의 특정 패키지를 재설치하려면:
$ uv tool upgrade black --reinstall-package click
도구 실행 시 추가 패키지를 포함할 수 있습니다:
$ uvx --with <extra-package> <tool>
도구 설치 시에도 포함할 수 있습니다:
$ uv tool install --with <extra-package> <tool-package>
--with 옵션은 여러 번 제공하여 추가 패키지를 포함할 수 있습니다.
--with 옵션은 패키지 사양을 지원하므로 특정 버전을 요청할 수 있습니다:
$ uvx --with <extra-package>==<version> <tool-package>
--with 옵션 대신 -w 단축어를 사용할 수 있습니다:
$ uvx -w <extra-package> <tool-package>
요청한 버전이 도구 패키지의 요구 사항과 충돌하면 패키지 해석이 실패하고 명령이 오류를 반환합니다.
도구를 설치할 때 동일한 도구 환경에 추가 패키지의 실행 파일도 포함하고 싶을 수 있습니다. 이는 함께 작동하는 관련 도구가 있거나 의존성을 공유하는 여러 실행 파일을 설치하고자 할 때 유용합니다.
--with-executables-from 옵션을 사용하면 기본 도구와 함께 설치할 실행 파일을 제공하는 추가 패키지를 지정할 수 있습니다:
$ uv tool install --with-executables-from <package1>,<package2> <tool-package>
예를 들어, ansible-core와 ansible-lint의 실행 파일과 함께 Ansible을 설치하려면:
$ uv tool install --with-executables-from ansible-core,ansible-lint ansible
이렇게 하면 ansible, ansible-core, ansible-lint 패키지의 모든 실행 파일이 동일한 도구 환경에 설치되어 모두 PATH에서 사용 가능해집니다.
--with-executables-from 옵션은 다른 설치 옵션과 함께 사용할 수 있습니다:
$ uv tool install --with-executables-from ansible-core --with mkdocs-material ansible
--with-executables-from과 --with의 차이점:
--with는 추가 패키지를 의존성으로 포함하지만 실행 파일은 설치하지 않습니다.--with-executables-from은 패키지를 의존성으로 포함하고 실행 파일도 설치합니다.각 도구 환경은 특정 Python 버전에 연결됩니다. uv가 다른 가상환경을 만들 때와 동일한 Python 버전 탐색 로직을 사용하지만, .python-version 파일이나 pyproject.toml의 requires-python 값과 같은 비전역 Python 버전 요청은 무시합니다.
--python 옵션으로 특정 버전을 요청할 수 있습니다. 자세한 내용은 Python 버전 문서를 참고하세요.
도구가 사용하는 Python 버전이 제거되면 도구 환경이 손상되어 도구를 사용할 수 없게 됩니다.
도구 실행 파일에는 Python 패키지가 제공하는 모든 콘솔 진입점, 스크립트 진입점, 바이너리 스크립트가 포함됩니다. 도구 실행 파일은 Unix에서는 심볼릭 링크로, Windows에서는 복사본으로 실행 파일 디렉터리에 저장됩니다.
참고: 도구 패키지 의존성이 제공하는 실행 파일은 설치되지 않습니다.
도구 실행 파일을 셸에서 사용하려면 실행 파일 디렉터리가 PATH 변수에 포함되어 있어야 합니다. 포함되어 있지 않으면 경고가 표시됩니다. uv tool update-shell 명령을 사용하면 일반적인 셸 설정 파일에 실행 파일 디렉터리를 PATH에 추가할 수 있습니다.
도구 설치 시, 이전에 uv로 설치하지 않은 실행 파일은 덮어쓰지 않습니다. 예를 들어, 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을 사용해야 합니다.
원문(영어): https://docs.astral.sh/uv/concepts/tools/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.