도구 사용하기

많은 파이썬 패키지는 도구로 활용할 수 있는 애플리케이션을 제공한다. uv는 이러한 도구를 쉽게 호출하고 설치할 수 있도록 특별히 설계된 기능을 갖추고 있다.

도구 실행하기

uvx 명령어를 사용하면 도구를 설치하지 않고 바로 실행할 수 있다.

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

$ uvx ruff

Note

이 명령어는 다음 명령어와 정확히 동일하다:

$ uv tool run ruff

uvx는 편의를 위해 제공하는 별칭이다.

도구 이름 뒤에 인자를 추가할 수도 있다:

$ uvx pycowsay hello from uv

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

uvx를 사용하면 도구가 임시로 생성된 격리된 환경에 설치된다.

Note

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

프로젝트가 평면 구조를 가지고 있다면(예: 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

@ 구문은 정확한 버전 외에는 사용할 수 없다는 점에 유의한다.

추가 기능 요청

--from 옵션을 사용하면 추가 기능과 함께 도구를 실행할 수 있다:

$ 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@3.2.4 httpie

심지어 특정 커밋을 가져올 수도 있다:

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

플러그인과 함께 사용하는 커맨드

추가적인 의존성을 포함시킬 수 있다. 예를 들어 mkdocs를 실행할 때 mkdocs-material을 포함시키려면 다음과 같이 한다:

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

도구 설치

특정 도구를 자주 사용한다면, uvx를 반복적으로 호출하는 대신 지속적인 환경에 설치하고 PATH에 추가하는 것이 유용하다.

Tip

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

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

$ uv tool install mkdocs --with mkdocs-material

도구 업그레이드

도구를 업그레이드하려면 uv tool upgrade 명령어를 사용한다:

$ uv tool upgrade ruff

도구 업그레이드는 설치 시 제공한 버전 제약 조건을 따른다. 예를 들어, uv tool install ruff >=0.3,<0.4를 실행한 후 uv tool upgrade ruff를 실행하면 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 버전 개념 페이지를 참고한다.

다음 단계

uv로 도구를 관리하는 방법에 대해 더 알고 싶다면 도구 개념 페이지와 커맨드 레퍼런스를 참고한다.

또는 프로젝트 작업하기를 계속 읽어본다.