Using uv to develop Python command-line applications#

Starting a new app with cookiecutter#

I already have a cookiecutter template I like using for CLI applications: simonw/click-app.

Thanks to uvx I don’t even need to install cookiecutter to use it:

1
uvx cookiecutter gh:simonw/click-app

This outputs a set of questions:

1
  [1/6] app_name (): demo-app
2
  [2/6] description (): Demo
3
  [3/6] hyphenated (demo-app):
4
  [4/6] underscored (demo_app):
5
  [5/6] github_username (): simonw
6
  [6/6] author_name (): Simon Willison

Which creates a demo-app directory containing the skeleton of a Python project.

Setting up the uv virtual environment#

uv has a number of different commands that can create and work with a .venv virtual environment directory.

1
cd demo-app

In this case, my pyproject.toml file (created by that cookiecutter template) defines a separate block of test dependencies. Here’s that TOML file in full:

1
[project]
2
name = "demo-app"
3
version = "0.1"
4
description = "Demo"
5
readme = "README.md"
6
authors = [{name = "Simon Willison"}]
7
license = {text = "Apache-2.0"}
8
requires-python = ">=3.8"
9
classifiers = [
10
    "License :: OSI Approved :: Apache Software License"
11
]
12
dependencies = [
13
    "click"
14
]
15

16
[build-system]
17
requires = ["setuptools"]
18
build-backend = "setuptools.build_meta"
19

20
[project.urls]
21
Homepage = "https://github.com/simonw/demo-app"
22
Changelog = "https://github.com/simonw/demo-app/releases"
23
Issues = "https://github.com/simonw/demo-app/issues"
24
CI = "https://github.com/simonw/demo-app/actions"
25

26
[project.scripts]
27
demo-app = "demo_app.cli:cli"
28

29
[project.optional-dependencies]
30
test = ["pytest"]

The [project.optional-dependencies] section lists that test block. I can create a new virtual environment in .venv/ and install both my project dependencies and those test dependencies like this:

1
uv sync --extra test

Here’s the output:

1
Using CPython 3.11.1
2
Creating virtual environment at: .venv
3
Resolved 9 packages in 207ms
4
   Built demo-app @ file:///private/tmp/for-uv/demo-app
5
Prepared 1 package in 614ms
6
Installed 6 packages in 8ms
7
 + click==8.1.7
8
 + demo-app==0.1 (from file:///private/tmp/for-uv/demo-app)
9
 + iniconfig==2.0.0
10
 + packaging==24.1
11
 + pluggy==1.5.0
12
 + pytest==8.3.3

Running the tests#

Now I can run pytest using the uv run command:

1
uv run pytest

1
==================== test session starts ====================
2
platform darwin -- Python 3.11.1, pytest-8.3.3, pluggy-1.5.0
3
rootdir: /private/tmp/for-uv/demo-app
4
configfile: pyproject.toml
5
collected 1 item
6

7
tests/test_demo_app.py .                                                                            [100%]
8

9
===================== 1 passed in 0.03s =====================

This runs the pytest binary in the current .venv/ environment. Note that I no longer have to “activate my virtual environment” - using uv run habitually solves that for me.

Running the CLI tool itself#

This line in pyproject.toml defines a script entry point for my CLI tool:

1
[project.scripts]
2
demo-app = "demo_app.cli:cli"

If the tool is correctly installed, I should be able to run it like this:

1
uv run demo-app

1
Usage: demo-app [OPTIONS] COMMAND [ARGS]...
2

3
  Demo
4

5
Options:
6
  --version  Show the version and exit.
7
  --help     Show this message and exit.
8

9
Commands:
10
  command  Command description goes here

I can also run it via Python like this (producing the same output):

1
uv run python -m demo_app

Crucially, the only reason this works is that I included this section in pyproject.toml:

1
[build-system]
2
requires = ["setuptools"]
3
build-backend = "setuptools.build_meta"

This may seem unrelated, but it’s necessary for the demo-app alias to be correctly installed. As Charlie Marsh explained it:

We support two kinds of projects: packages and non-packages. You want the former in this case, because you actually want to install the package in the environment. (We used to require this, but a lot of people want to be able to create lightweight projects that are just collections of scripts and don’t need to be buildable / installable into an environment. We call those non-package projects.)

We consider a project to be a “package” if [build-system] is defined or you set tool.uv.package = true

Otherwise, we don’t install the project itself into the environment.

Using dev-dependencies instead#

The only reason I needed to use uv sync here was to specify that --extra test to get my test dependencies installed as well.

As an aside, the following would have worked instead:

1
uv run --extra test pytest

I’d only need to pass that --extra test option the first time I ran uv run - on subsequent runs the test dependencies would already be installed.

Another option here would be to use the newer concept of dev-dependencies. uv supports these right now, and they’ve just been standardized by PEP 735. To use those, add this to the pyproject.toml file:

1
[tool.uv]
2
dev-dependencies = ["pytest"]

Then uv run pytest would work without needing to use --extra to ensure the test dependencies are installed, and without needing to use uv sync at all.

There’s no need for uv pip#

I got into a tangle at first trying to figure this out, because I thought I needed to use uv pip to manage my environment… and it turns out uv pip followed these rules:

When running a command that mutates an environment such as uv pip sync or uv pip install, uv will search for a virtual environment in the following order:

• An activated virtual environment based on the VIRTUAL_ENV environment variable.
• An activated Conda environment based on the CONDA_PREFIX environment variable.
• A virtual environment at .venv in the current directory, or in the nearest parent directory.

Update: This changed in uv 0.5.0 so Conda should no longer result in this confusion.

I had Conda installed, which means I had a CONDA_PREFIX environment variable set, which meant uv pip was ignoring my .venv directory entirely and using the Conda environment instead!

This caused all manner of confusion. I put together this document and asked Charlie for help, and he graciously unblocked me.