uv and PEP 723#

I have recently started using uv a lot, specially for quick standalone scripts, most of these scripts are generated by various LLMs for different tasks. The biggest pain point I had with these scripts was to setup a virtual env, installing the packages and asking ChatGPT and other LLMs to give me requirements file/list.

uv changed that by utilizing PEP 723 and embedding these requirement inline to the script.

At Diversio, I frequently use GitHub Copilot a lot, and there I’ve added a small instruction to make sure it’s embedding the requirements in the script itself.

When asked to generate a uv based Python script, at the very top of the file, insert an inline metadata block listing all external packages in this format:

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

Now, I gave it the prompt:

Give me a uv based Python script that pings google.com and prints the output in colorful tabular format.

You can see its output here

➜ uv run uv_pep_723_example.py
Installed 9 packages in 207ms
Pinging google.com 5 times...
Ping 1: Success - 221.01 ms
Ping 2: Success - 461.52 ms
Ping 3: Success - 288.88 ms
Ping 4: Success - 216.29 ms
Ping 5: Success - 205.57 ms

                 HTTP Ping Results for google.com
┏━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ # ┃ Timestamp           ┃ Host       ┃ Status  ┃ Response Time ┃
┡━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ 1 │ 2025-03-05 00:25:16 │ google.com │ Success │     221.01 ms │
│ 2 │ 2025-03-05 00:25:18 │ google.com │ Success │     461.52 ms │
│ 3 │ 2025-03-05 00:25:19 │ google.com │ Success │     288.88 ms │
│ 4 │ 2025-03-05 00:25:20 │ google.com │ Success │     216.29 ms │
│ 5 │ 2025-03-05 00:25:22 │ google.com │ Success │     205.57 ms │
└───┴─────────────────────┴────────────┴─────────┴───────────────┘

Summary Statistics:
  Successful requests: 5/5
  Min/Avg/Max: 205.57/278.65/461.52 ms
  Standard Deviation: 107.35 ms

Where is uv storing these packages?#

➜ ls -l ~/.cache/uv/environments-v2/uv-pep-723-example-af4300630d2aced4/lib/python3.12/site-packages
total 12
drwxr-xr-x  3 monty staff   96 Mar  5 00:25 __pycache__
drwxr-xr-x  8 monty staff  256 Mar  5 00:25 certifi
drwxr-xr-x  9 monty staff  288 Mar  5 00:25 certifi-2025.1.31.dist-info
drwxr-xr-x 17 monty staff  544 Mar  5 00:25 charset_normalizer
drwxr-xr-x 10 monty staff  320 Mar  5 00:25 charset_normalizer-3.4.1.dist-info
drwxr-xr-x 12 monty staff  384 Mar  5 00:25 idna
drwxr-xr-x  8 monty staff  256 Mar  5 00:25 idna-3.10.dist-info
drwxr-xr-x 23 monty staff  736 Mar  5 00:25 markdown_it
drwxr-xr-x 10 monty staff  320 Mar  5 00:25 markdown_it_py-3.0.0.dist-info
drwxr-xr-x  9 monty staff  288 Mar  5 00:25 mdurl
drwxr-xr-x  8 monty staff  256 Mar  5 00:25 mdurl-0.1.2.dist-info
drwxr-xr-x 22 monty staff  704 Mar  5 00:25 pygments
drwxr-xr-x  9 monty staff  288 Mar  5 00:25 pygments-2.19.1.dist-info
drwxr-xr-x 21 monty staff  672 Mar  5 00:25 requests
drwxr-xr-x  9 monty staff  288 Mar  5 00:25 requests-2.32.3.dist-info
drwxr-xr-x 82 monty staff 2624 Mar  5 00:25 rich
drwxr-xr-x  8 monty staff  256 Mar  5 00:25 rich-13.9.4.dist-info
drwxr-xr-x 19 monty staff  608 Mar  5 00:25 urllib3
drwxr-xr-x  8 monty staff  256 Mar  5 00:25 urllib3-2.3.0.dist-info
-rw-r--r--  1 monty staff   18 Mar  5 00:25 _virtualenv.pth
-rw-r--r--  1 monty staff 4342 Mar  5 00:25 _virtualenv.py

The cache can be cleaned using the uv cache clean command as specified here.

References#

• https://peps.python.org/pep-0723/
• https://docs.astral.sh/uv/guides/scripts/#declaring-script-dependencies
• https://docs.astral.sh/uv/concepts/cache/#clearing-the-cache