Amp your Python superpowers with ‘uv run’

Astral’s uv tool makes setting up Python environments and projects fast and easy. It also gives you tools for running existing Python packages and libraries without having to formally install them.

When you use uv run to execute a Python program, uv automatically fetches the needed components, sets up a temporary environment for them, and launches the program. uv stage-manages these tasks automatically, so developers can just get on with the show.

The basics of ‘uv run’ for packages and libraries

When you use uv run, you normally just pass in the name of the Python program you want executed. As an example, passing uv run myfile.py runs myfile.py “as is,” with only whatever is currently installed in the environment uv run is using. If the program requires any uninstalled third-party dependencies, it won’t be able to find them.

If you want to add those dependencies, you can add the --with flag to uv run. If you needed the third-party library NumPy for your program, for instance, you’d type:

uv run --with numpy myfile.py

If you need to add multiple dependencies, just separate them with commas:

uv run --with numpy,matplotlib myfile.py

You can also pin specific versions using the syntax found elsewhere in Python:

uv run --with numpy==2.0 myfile.py

What happens under the hood?

When you run uv run using --with, uv contacts PyPI and tries to download the requirement you’ve named and the appropriate version if you’ve supplied one. If the requirement is provided as a wheel, it’ll use that; if not, it’ll obtain the source and try to compile it for your current platform.

Next, uv caches the resulting download in the directory found in your user profile. After that, the program you selected will run with the downloaded requirements.

The first time uv fetches a requirement from PyPI, you’ll see feedback about the download process in the console. Depending on how many requirements there are and how big they are, this may take some time. But on subsequent runs, if you ask for the same requirements, they’ll be obtained out of the local cache, and so will start almost instantly.

Speaking of caching, uv manages its package cache automatically, but if you want to force-erase it, you can use the command uv cache clean. If you want to avoid using the local cache (without having to clean it out), you can use the -n flag: uv run -n --with....

Using ‘uv run’ on a package with local source

If you have a package’s source available locally with a pyproject.toml file in it—such as from a clone of a Git repository—you can use uv run on it as well, with the same behaviors.

In the root directory of the package—where the pyproject.toml file lives—type uv run and then either the name of a package to execute from the project, or the name of an entry point for the package.

For instance, if the project was named proj, and it had a module named cmd to open an interactive console for the project, you’d type:

uv run -m proj.cmd

If the project had a command-line entry point named proj_cmd, you would type:

uv run proj_cmd

If you just type uv_run, uv will attempt to determine what entry point commands (not what modules) are available for the current project.

You can also invoke Python with the package as part of the environment it’s running in by typing, uv run python. You can then supplement this command with any number of additional switches or options you’d normally pass to Python. For instance, the command uv run python -m proj.cmd would have the same effect as uv run -m proj.cmd.