Your type checker can't see a script's dependencies. uv check --script can.

Ask a coding agent for a quick Python script and you'll often get one file that imports a package your project doesn't have. Run a type checker over it and the checker can't find that package. So it reports an import error and then treats everything from that package as unknown. Any mistake in how the script calls the library gets through.

Astral's post on putting its package manager uv and its type checker ty together was on the Hacker News front page today. The useful part for builders is one command: uv check --script your_script.py. It reads the script's own dependency list, sets up an environment for that list, and then type-checks the script against it.

What the script needs. A PEP 723 header, which is a comment block at the top listing what the script depends on:

# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx>=0.28"]
# ///

You don't have to write it by hand. uv add --script bare.py httpx added that block to a plain file for us. Astral says script support needs uv 0.12.3 or later and ty 0.0.76 or later. We used uv 0.13.5 (out October 21) and ty 0.0.91 (out October 22). uv check downloaded ty on first use.

Our test. We wrote a small script that fetches a GitHub repo's star count with httpx and planted two bugs. It calls r.json_data(), which doesn't exist (the method is r.json()), and it adds an int to a string.

Plain ty check fetch_stars.py, with no environment set up: "Cannot resolve imported module httpx", plus the int-plus-string error. The json_data bug wasn't flagged.
uv check --script fetch_stars.py: both bugs, including "Object of type Response has no attribute json_data", and exit code 1. It took 1.3 seconds the first time, including the ty download, and 0.27 seconds once cached.
TY_UV=scripts ty check gave the same two errors. Astral documents that setting for running ty directly. In VS Code, the ty extension's setting is "ty.experimental.useUv": "on".
Just running it with uv run fetch_stars.py also hit the bug, but only after it had already called the GitHub API. A script that writes files or sends messages would have done that part first.
With both bugs fixed: "All checks passed!", exit 0.

Who it's for. Anyone who keeps one-off scripts in a repo (data pulls, eval runners, glue code an agent wrote) and wants them checked against what they actually import. Put uv check --script in a pre-commit hook or CI step, or give it to your agent as the check to run before it says it's done. In a normal uv project, plain uv check syncs the environment and runs ty over the project. Astral says it uses the ty version recorded in your lockfile.

The catch. It's labelled experimental, and every run prints a warning that it "may change without warning." Setting up the environment means installing the script's dependencies, and Astral points out that installing packages can run third-party code. That's why the editor and TY_UV routes are opt-in, so only check scripts whose dependency list you'd be willing to install. A type checker also only knows what types know. r.json() returns untyped data, so when we misspelled the JSON key (stargazer_count), it said "All checks passed!" and the script would still fail at runtime.

Our take

If your agent writes Python scripts, make uv check --script the gate before anything runs. It's one command, it took under two seconds here, and in our test it caught the bug a plain type check missed. Keep the header honest, review the dependency list, and keep a real test for the parts no type checker can see.

What we did and didn't do: we ran every command above on a Linux box on October 23, 2026, in a throwaway folder. We didn't test the VS Code extension, workspaces with --all-packages, --fix, Windows or macOS. Facts come from Astral's blog post, the uv docs and CLI reference, PEP 723, and the uv and ty GitHub releases, all read today. Not sponsored; no affiliate links.

MODEL Editors