Brief Tutorial on UV Usage

🛠 Tools and Programming
1

This article is transcoded by SimpRead, original address www.studywithgpt.com

This chapter introduces how to use tools in Python, focusing on the uv package, including how to run, install, upgrade tools, and how to handle specific versions and sources.

Using UV Tools in Python

This chapter mainly focuses on how to use the uv package in Python, covering its installation, running, upgrading tools, and handling specific versions and sources, providing practical examples for better understanding.

1. Installing UV Tools

Before using the uv tool, users need to ensure the uv package is installed. It can be installed via Python’s package management tools. For example, using pip you can run the following command:

$ pip install uv

After installation, users can start using the various tools provided by uv.

2. Running Tools

In uv, users can run tools using the uvx command without installing them. For example, to run the ruff tool, use the following command:

$ uvx ruff

Note that the usage of the uvx command is equivalent to the following command:

$ uv tool run ruff

Here, uvx is merely a convenient alias.

Users can provide parameters after the tool name. For example, when running the pycowsay tool, you can enter:

$ uvx pycowsay hello from uv

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

When running tools with uvx, the tool is installed into a temporary, isolated environment.

3. Commands and Different Package Names

When users run uvx ruff, uv installs the ruff package which provides the ruff command. However, sometimes the package name and command name may differ. To call a command from a specific package, users can use the --from option. For example, to use the http command, which is provided by the httpie package:

$ uvx --from httpie http

4. Requesting Specific Versions

If users want to run a specific version of a tool, they can use the command@<version> syntax. For example, to run a specific version of ruff, you can enter:

$ uvx ruff@0.3.0 check

To run the latest version, you can use command@latest:

$ uvx ruff@latest check

Users can also specify the package version with the --from option:

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

Additionally, version ranges can be constrained:

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

Note that the @ syntax can only be used for exact versions.

5. Requesting Different Sources

Users can also use the --from option to install tools from alternative sources. For example, to pull a package from git, run:

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

6. Handling Commands with Plugins

When running certain commands, users can include additional dependencies. For example, to include mkdocs-material when running mkdocs, run:

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

7. Installing Tools

If users frequently use a certain tool, they can choose to install it into a persistent environment and add it to the PATH instead of repeatedly using uvx. For example, to install ruff, run:

$ uv tool install ruff

After installation, the executable will be placed in the bin directory within PATH, so the tool can be run without using uv. If not added to PATH, the system will display a warning, and users can use uv tool update-shell to add it to PATH.

After installing ruff, users can verify its availability:

$ ruff --version

Note that unlike uv pip install, installing a tool does not make its modules available in the current environment. For example, the following command will fail:

$ python -c "import ruff"

This isolation is important to reduce interference and conflicts between tools, scripts, and projects.

Unlike uvx, uv tool install operates on a package and installs all executables provided by that tool. For example, the following command installs http, https, and httpie executables:

$ uv tool install httpie

Users can also include package versions without using --from:

$ uv tool install 'httpie>0.1.0'

Likewise, users can specify the package source:

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

Like uvx, installation can also include extra packages:

$ uv tool install mkdocs --with mkdocs-material

8. Upgrading Tools

Users can use the uv tool upgrade command to upgrade tools. For example, to upgrade ruff, run:

$ uv tool upgrade ruff

Tool upgrades will follow the version constraints provided at installation. For example, if a user ran uv tool install ruff >=0.3,<0.4 and then uses uv tool upgrade ruff, ruff will upgrade to the latest version within that range.

To replace the version constraints, users can reinstall the tool:

$ uv tool install ruff>=0.4

Users can also upgrade all tools at once:

$ uv tool upgrade --all

9. Conclusion

By following the above steps, users should be able to effectively use uv tools in Python. Whether installing, running, upgrading tools, or managing specific versions and sources, uv provides a flexible mechanism to meet development needs. Through practice and application, users will be proficient with this tool and improve development efficiency.

More

uv简介——python编程神级工具