도구 사용

많은 Python 패키지(package)는 도구(tool)로 사용할 수 있는 애플리케이션을 제공합니다. uv는 도구를 쉽게 실행하고 설치할 수 있도록 전용 지원을 제공합니다.

도구 실행

uvx 명령은 도구를 설치하지 않고 실행합니다.

예를 들어, ruff를 실행하려면:

$ uvx ruff

참고

이것은 다음과 정확히 동일합니다:

bash $ uv tool run ruff

uvx는 편의를 위한 별칭(alias)입니다.

도구 이름 뒤에 인수를 제공할 수 있습니다:

$ uvx pycowsay hello from uv

 -----------
< hello from uv >
 -----------
  \   ^__^
   \  (oo)\_______
      (__)\       )\/\
          ||----w |
          ||     ||

uvx를 사용하면 도구가 임시 격리 환경에 설치됩니다.

참고

_프로젝트_에서 도구를 실행할 때 도구가 프로젝트 설치를 필요로 하는 경우(예: pytest나 mypy 사용 시), uvx 대신 uv run을 사용하세요. 그렇지 않으면 도구가 프로젝트와 격리된 가상환경(virtual environment)에서 실행됩니다.

프로젝트가 플랫 구조(예: 모듈에 src 디렉터리를 사용하지 않는 구조)인 경우에는 프로젝트 자체를 설치할 필요가 없으므로 uvx를 사용해도 됩니다. 이 경우 uv run은 프로젝트 의존성에 도구 버전을 고정하려는 경우에만 유용합니다.

패키지 이름이 다른 명령

uvx ruff를 실행하면 uv는 ruff 명령을 제공하는 ruff 패키지를 설치합니다. 그러나 패키지 이름과 명령 이름이 다른 경우도 있습니다.

--from 옵션을 사용해 특정 패키지에서 명령을 실행할 수 있습니다. 예를 들어, httpie가 제공하는 http 명령:

$ uvx --from httpie http

특정 버전 요청

특정 버전의 도구를 실행하려면 command@<version>을 사용하세요:

$ uvx ruff@0.3.0 check

최신 버전의 도구를 실행하려면 command@latest를 사용하세요:

$ uvx ruff@latest check

--from 옵션으로도 패키지 버전을 지정할 수 있습니다:

$ uvx --from 'ruff==0.3.0' ruff check

또는 버전 범위로 제약할 수 있습니다:

$ uvx --from 'ruff>0.2.0,<0.3.0' ruff check

@ 구문은 정확한 버전 지정 이외에는 사용할 수 없습니다.

extras 요청

--from 옵션을 사용해 extras와 함께 도구를 실행할 수 있습니다:

$ uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

버전 선택과 결합할 수도 있습니다:

$ uvx --from 'mypy[faster-cache,reports]==1.13.0' mypy --xml-report mypy_report

다른 소스 요청

--from 옵션을 사용해 대체 소스에서 설치할 수도 있습니다.

예를 들어, git에서 가져오려면:

$ uvx --from git+https://github.com/httpie/cli httpie

특정 브랜치의 최신 커밋을 가져올 수도 있습니다:

$ uvx --from git+https://github.com/httpie/cli@master httpie

특정 태그를 가져오거나:

$ uvx --from git+https://github.com/httpie/cli@v3.0.0 httpie

특정 커밋을 가져올 수도 있습니다:

$ uvx --from git+https://github.com/httpie/cli@2843b87 httpie

Git LFS 지원으로 가져오려면:

$ uvx --lfs --from git+https://github.com/astral-sh/lfs-cowsay lfs-cowsay

플러그인이 있는 명령

추가 의존성을 포함할 수 있습니다. 예를 들어, mkdocs를 실행할 때 mkdocs-material을 포함하려면:

$ uvx --with mkdocs-material mkdocs --help

도구 설치

도구를 자주 사용한다면 uvx를 반복 실행하는 대신 영구 환경에 설치하고 PATH에 추가하는 것이 유용합니다.

팁

uvx는 uv tool run의 편리한 별칭입니다. 도구와 상호작용하는 다른 모든 명령은 전체 uv tool 접두사가 필요합니다.

ruff를 설치하려면:

$ uv tool install ruff

도구를 설치하면 실행 파일이 PATH의 bin 디렉터리에 배치되어 uv 없이도 도구를 실행할 수 있습니다. PATH에 없으면 경고가 표시되며, uv tool update-shell을 사용해 PATH에 추가할 수 있습니다.

ruff를 설치한 후 다음과 같이 사용할 수 있습니다:

$ ruff --version

uv pip install과 달리, 도구를 설치해도 해당 모듈이 현재 환경에서 사용 가능하게 되지는 않습니다. 예를 들어, 다음 명령은 실패합니다:

$ python -c "import ruff"

이 격리는 도구, 스크립트, 프로젝트 간의 의존성 충돌을 줄이는 데 중요합니다.

uvx와 달리 uv tool install은 패키지 단위로 동작하며, 도구가 제공하는 모든 실행 파일을 설치합니다.

예를 들어, 다음 명령은 http, https, httpie 실행 파일을 모두 설치합니다:

$ uv tool install httpie

--from 없이도 패키지 버전을 지정할 수 있습니다:

$ uv tool install 'httpie>0.1.0'

패키지 소스도 마찬가지로 지정할 수 있습니다:

$ uv tool install git+https://github.com/httpie/cli

Git LFS를 사용하는 패키지 소스:

$ uv tool install --lfs git+https://github.com/astral-sh/lfs-cowsay

uvx와 마찬가지로 설치 시 추가 패키지를 포함할 수 있습니다:

$ uv tool install mkdocs --with mkdocs-material

--with-executables-from 플래그를 사용하면 여러 관련 실행 파일을 같은 도구 환경에 함께 설치할 수 있습니다. 예를 들어, 다음 명령은 ansible의 실행 파일과 함께 ansible-core 및 ansible-lint가 제공하는 실행 파일도 설치합니다:

$ uv tool install --with-executables-from ansible-core,ansible-lint ansible

도구 업그레이드

도구를 업그레이드하려면 uv tool upgrade를 사용하세요:

$ uv tool upgrade ruff

도구 업그레이드는 설치 시 제공된 버전 제약을 준수합니다. 예를 들어, uv tool install ruff >=0.3,<0.4로 설치한 후 uv tool upgrade ruff를 실행하면 >=0.3,<0.4 범위 내의 최신 버전으로 업그레이드됩니다.

버전 제약을 교체하려면 uv tool install로 재설치하세요:

$ uv tool install ruff>=0.4

모든 도구를 업그레이드하려면:

$ uv tool upgrade --all

Python 버전 요청

기본적으로 uv는 도구를 실행, 설치, 업그레이드할 때 기본 Python 인터프리터(처음 발견된 것)를 사용합니다. --python 옵션으로 사용할 Python 인터프리터를 지정할 수 있습니다.

예를 들어, 도구를 실행할 때 특정 Python 버전을 요청하려면:

$ uvx --python 3.10 ruff

도구를 설치할 때:

$ uv tool install --python 3.10 ruff

도구를 업그레이드할 때:

$ uv tool upgrade --python 3.10 ruff

Python 버전 요청에 대한 자세한 내용은 Python 버전 개념 페이지를 참조하세요.

레거시 Windows 스크립트

도구는 레거시 setuptools 스크립트 실행도 지원합니다. 설치 시 이 스크립트는 $(uv tool dir)\<tool-name>\Scripts에서 사용할 수 있습니다.

현재 .ps1, .cmd, .bat 확장자를 가진 레거시 스크립트만 지원됩니다.

예를 들어, 다음은 Command Prompt 스크립트를 실행하는 예입니다.

$ uv tool run --from nuitka==2.6.7 nuitka.cmd --version

확장자를 지정하지 않아도 됩니다. uvx는 자동으로 .ps1, .cmd, .bat 순서로 파일을 찾아 실행합니다.

$ uv tool run --from nuitka==2.6.7 nuitka --version

다음 단계

uv로 도구를 관리하는 방법에 대해 더 알아보려면 도구 개념 페이지와 명령 참조를 확인하세요.

또는 계속 읽어 프로젝트를 작업하는 방법을 알아보세요.

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

원문(영어): https://docs.astral.sh/uv/guides/tools/