Using uv and PEP 723 for Self-Contained Python Scripts

> Making an HTTP request js pretty basic stuff for a scripting language, you shouldn’t need or want a library for it.

Sometimes languages/runtimes move slowly :) Speaking as a JS developer, this is how we made requests for a long time (before .fetch), inside the browser which is basically made for making requests:

    var xhr = new XMLHttpRequest();
    xhr.open('POST', 'https://example.com', true);
    xhr.setRequestHeader('Content-type', 'application/x-www-form-urlencoded');
    xhr.onload = function () {
        console.log(this.responseText);
    };
    xhr.send('param=add_comment');

It has two! — http.client and urllib.request — and they are really usable.

Lots of people just like requests though as an alternative, or for historical reasons, or because of some particular aspect of its ergonomics, or to have a feature they’d rather have implemented for them than have to write in their own calling code.

At this stage it’s like using jQuery just to find an element by css selector (instead of just using document.querySelector.)

They could have used a database driver for msql, postgresql or mongodb for a more realistic example (very common for sysadmin type scripts that are only used once and then thrown away) and your complaint would be invalid, but then you'd have to set up the database and the example would no longer be fit for a quick blog post that gives you the opportunity to just copy paste the code and run it for yourself.

The standard library does not give you a possibility to do async HTTP requests, that's what httpx does. As Python still heavily relies on async this is really a bummer.

I talked about that in my readme https://github.com/gabrielsroka/r

requests is really useful for non-trivial http requests (especially as urllib has terrible defaults around REST style interactions).

But here all the script is going is a trivial GET, that’s

    urllib.request.urlopen(url)

I agree. Requests is an embarrassment and indictment of the Python standard library. And so are dataclasses. They just should have subsumed attrs.

uv v0.6.10 has just been released with a more convenient way of doing this:

    uv python find --script foo.py

— https://docs.astral.sh/uv/reference/cli/#uv-python-find--scr...

https://pyproject-nix.github.io/uv2nix/usage/inline-metadata... might be an option for you.

My general solution to project management problems with PEP 723 scripts is to develop the script as a regular Python application that has `pyproject.toml`. It lets you use all of your normal tooling. While I don't use an LSP-based editor, it makes things easy with Ruff and Pyright. I run my standard Poe the Poet (https://poethepoet.natn.io/) tasks for formatting, linting, and type checking as in any other project.

One drawback of this workflow is that by default, you duplicate the dependencies: you have them both in the PEP 723 script itself and `pyproject.toml`. I just switched a small server application from shiv (https://github.com/linkedin/shiv) to inline script metadata after a binary dependency broke the zipapp. I experimented with having `pyproject.toml` as the single source of truth for metadata in this project. I wrote the following code to embed the metadata in the script before it was deployed on the server. In a project that didn't already have a build and deploy step, you'd probably want to modify the PEP 723 script in place.

  #! /usr/bin/env python3
  # License: https://dbohdan.mit-license.org/@2025/license.txt
  
  import re
  import tomllib
  from pathlib import Path
  from string import Template
  
  import tomli_w
  
  DEPENDENCIES = "dependencies"
  PROJECT = "project"
  REQUIRES_PYTHON = "requires-python"
  
  DST = Path("bundle.py")
  PYPROJECT = Path("pyproject.toml")
  SRC = Path("main.py")
  
  BUNDLE = Template(
      """
  #! /usr/bin/env -S uv run --quiet --script
  # /// script
  $toml
  # ///
  
  $code
  """.strip()
  )
  
  
  def main() -> None:
      with PYPROJECT.open("rb") as f:
          pyproject = tomllib.load(f)
  
      toml = tomli_w.dumps(
          {
              DEPENDENCIES: pyproject[PROJECT][DEPENDENCIES],
              REQUIRES_PYTHON: pyproject[PROJECT][REQUIRES_PYTHON],
          },
          indent=2,
      )
  
      code = SRC.read_text()
      code = re.sub(r"^#![^\n]+\n", "", code)
  
      bundle = BUNDLE.substitute(
          toml="\n".join(f"# {line}" for line in toml.splitlines()),
          code=code,
      )
  
      DST.write_text(bundle)
  
  
  if __name__ == "__main__":
      main()

Out of curiosity, what are some problems with rustification? Is it an aversion to Rust specifically or a dislike of the ecosystem tools not being written in Python?

The former is subjective, but the latter seems like not really much of an issue compared to the language itself being written in C.

    I also modified a script I've been using for a few years to patch pylsp so it can now see uv script envs using the "uv sync --dry-run --script <path>" hack.

what's the --dry-run hack ?

Thanks for the positive feedback! I was curious too and thought others would enjoy hearing what I learned.

> This is neat writeup on use of uv, but it doesn't solve the "how to give self contained script to grandma" problem.

Not at the moment, but will your grandma run a script? There is an interesting thing you can already do today for larger applications which is to install uv alongside your app. You can make a curl-to-bash thing or similar that first installs uv into a program specific location to then use that to bootstrap your program. Is it a good idea? I don't know, but you can do that.

For simple scripts (I never succeeded using it on something really complex, but it's great when you don't want to use bash but need something like Python) I had used this approach that still works nowadays and has no uv dependency (only requires pip to be installed in the same Python interpreter that you're using to run your script):

https://www.franzoni.eu/single-file-editable-python-scripts-...

You can write a bash shebang that curl into shell. Unfortunately when I did it and gave to grandma it has failed because grandma has substituted oil shell and linked it as sh which is not best practice. I think grandmother shell script is simply impossible. They have spent decades acquiring idiosyncratic unix environment

For this case, it might be easier to package the script using pyinstaller. That way, she can just run it. Packaging it that way is more work on your side though.

I think uv should become a default package for most operating systems.

well you can just give her the `./install_uv.sh && ./run_script.sh` command, eg

`( curl -LsSf https://astral.sh/uv/install.sh | sh ) && ./run_script.sh`

Next up: uv competitor compiled with cosmopolitan libc.

As mentioned in the article, along with PDM.

Oh hey, I have seen your post. Making a script download the dependencies on its own is an interesting challenge. I am a big fan of inline script metadata in Python, and I was an early adopter when pipx implemented PEP 722 (the precursor to PEP 723), but I made my version for fun.

https://pip.wtf/ was on HN not that long ago (https://news.ycombinator.com/item?id=38383635). I had my own take on it that used virtual environments, supported Windows, and was d a free license: https://github.com/dbohdan/pip-wtenv.

I totally agree, but uv is the real deal. It's not another Poetry, Pipenv, etc.

uv takes Python infra from "jesus this is awful" to "wow this is actually quite nice". It is a game changer.

You should really try it now. Waiting 5 years is just needless self-flagellation.

IMO the only risk is that Astral run out of money, but given how dire the situation without uv is, I'd say it's easily worth the risk.

Speaking as someone who enjoys reading after dark, I like lanterns, but I consider the ecosystem dire. No one seems able to propose a solution to the problem of how do I keep this lantern lit all night without soot and fuel on my hands. At home I refuse to try any fuel that I can't get from the meatpacker's leftovers anyway. If people are still talking about electricity and bulbs in five year's time, maybe I'll give it a go then.

I've used plenty, but uv is basically a one stop shop with a logical workflow.

It has sane defaults so really I'd recommend most people just use it for everything, unless they some very specific reasons not to.