Python Project Management with uv

Properties2

Type	Practice
Note created	Feb 17, 2025

uv includes some commands to help manage complete Python projects.

uv init

The init commands creates a basic project layout, which consists in:

• An empty README.md file (except when using --no-readme),
• A pyproject.toml file with some sensible placeholders,
• A src/<project_name> directory (which is a strongly recommended layout)

uv add / uv remove

Adds or removes dependencies from the pyproject.toml definition. uv add includes the expected syntaxes to add different requests:

# Add a simple PyPI dependency
uv add requests
 
# Pin a given version
uv add 'requests==2.31.0'
 
# Add a git dependency
uv add requests --git https://github.com/psf/requests

If needed, uv also supports extended package sources.

uv run

The run command will enable the appropriate virtual environment, which is isolated from the shell by default. When working with projects, we need to manually define at least an entrypoint, by adding for example:

[project.scripts]
testing_uv = "testing_uv:hello"

That way, we can then run uv run -- testing_uv, ensuring the same isolation as a potential user of the package. This command will run all kinds of binaries installed in the environment, for example: uv run -- flask run -p 3000. The -- notation is not strictly needed (I just enjoy the separation from the command to be run).

In case the isolation is annoying, a shell can be instructed to include the environment by running source .venv/bin/activate or each shell’s equivalent.