Uv: Running a script with dependencies
docs.astral.sh474 points by Bluestein 21 hours ago
474 points by Bluestein 21 hours ago
The "declaring script dependencies" thing is incredibly useful: https://docs.astral.sh/uv/guides/scripts/#declaring-script-d...
# /// script
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests, rich
# ... script goes here
It's an implementation of Python PEP 723: https://peps.python.org/pep-0723/
Claude 4 actually knows about this trick, which means you can ask it to write you a Python script "with inline script dependencies" and it will do the right thing, e.g. https://claude.ai/share/1217b467-d273-40d0-9699-f6a38113f045 - the prompt there was:
Write a Python script with inline script
dependencies that uses httpx and click to
download a large file and show a progress bar
shebang mode is also incredibly useful and allows execution like ./script.sh
#!/usr/bin/env -S uv run --script
# /// script
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests, rich
# ... script goes hereI really love this and I've been using it a lot. The one thing I'm unsure about is the best way to get my LSP working with inline dependencies.
Usually, when I use uv along with a pyproject.toml, I'll activate the venv before starting neovim, and then my LSP (basedpyright) is aware of the dependencies and it all just works. But with inline dependencies, I'm not sure what the best way to do this is.
I usually end up just manually creating a venv with the dependencies so I can edit inside of it, but then I run the script using the shebang/inline dependencies when I'm done developing it.
Yeah i don't think there is a neater way to do this right now. One thing that maybe saves some effort is a "uv sync" will pay attention to the $VIRTUAL_ENV env var, but only if that var points to a venv that already exists. You can't point to an empty dir and have it create the venv.
# make a venv somehow, probably via the editor so it knows about the venv, saving a 3rd step to tell it which venv to use
$ env VIRTUAL_ENV=.venv/ uv sync --script foo.py
I'd encourage using --dry-run before running uv sync, by default it can be destructive.
By default, an exact sync is performed: uv removes packages that are not declared as dependencies of the project. Use the `--inexact` flag to keep extraneous packages.This was my contribution to their docs, happy to see people find it useful :)
'env -s' it's not portable.
Should be portable as long as there are no quotes. It’s basically a nop on macOS since in macOS the shebang args are already split by spaces (even when quoted).
Edit: further reading <https://unix.stackexchange.com/a/605761/472781> and <https://unix.stackexchange.com/a/774145/472781> and also note that on older BSDs it also used to be like that
Not under OpenBSD.
Thanks for pointing it out.
Indeed, OpenBSD’s and NetBSD’s `env` does not support `-S`. DragonflyBSD does (as expected).
Solaris as pointed out by the first link doesn’t even support more than one argument in the shebang so no surprise that its `env` does not support it either. Neither does IllumOS (but not sure about the shebang handling)
> without you having to think about them at all.
Hahahahaha.
Oh. I'm rolling on the floor. Hahahahaha.
How do you never learn? No, honestly, how do you never learn this simple thing: it will break! I will bet my pension on that it will break, and perhaps not you, but some hundreds of developers will have to try to debug and try to figure out where the dependencies went and why they weren't installed correctly, or why something was missing and so on.
There will never be a situation that you don't have to think about something as important as dependencies at all.
PEP723 is also supported by pipx and hatch, even though uv is (deservedly) getting all the attention these days.
Others like pip-tools have support in the roadmap (https://github.com/jazzband/pip-tools/issues/2027)
I plan to support it in PAPER as well. A big part of the original rationale for PEP 723 (and 722) was to support people who want to distribute a single Python file to colleagues etc. without worrying about Python packaging (or making a "project"), and allow them to run it with the appropriate dependencies and their own local Python. So while I am trying to make a tool for users (that incidentally covers a portion of developer use cases) rather than developers, this definitely fits.
I thought that was a heart emoticon next to requests, for a second.
I mean, who doesn't love requests?
Well... maybe the people who have stopped working on it due to the mysterious disappearance of 30,000 fundraised dollars, selling paid support but "delegat[ing] the actual work to unpaid volunteers", and a pattern of other issues from other community members who have not spoken up about them.
https://vorpus.org/blog/why-im-not-collaborating-with-kennet...
> he said his original goal was just to raise $5k to buy a computer. Privately, I was skeptical that the $5k computer had anything to do with Requests. Requests is a small pure-Python library; if you want to work on it, then any cheap laptop is more than sufficient. $5k is the price of a beefy server or top-end gaming rig.
Kenneth Reitz has probably done more to enrich my life than most anyone else who builds things. I wouldn't begrudge him the idea of a nice workstation for his years of labour. Yeah, he's very imperfect, but the author has absolutely lost me
What has he built that you like using that much? Honest question, not being snarky.
I liked Requests way back when but prefer httpx or aiohttp. I liked piping for about a month when it first came out, but jumped ship pretty quickly. I'm not familiar with his other works.
I also wouldn't begrudge the guy a laptop, but I do get what the author was saying. His original fundraiser felt off, like, if you want a nice laptop, just say so, but don't create specious justifications for it.
> I liked Requests way back when but prefer httpx or aiohttp.
Those two tools are modeled after `requests`, so Reitz still has an influence in your life even if you don't use his implementation directly.
They’re pretty close, sure, but Requests itself basically models a web browser. The newer ones model newer browsers (eg with HTTP/2 and async).
Kenneth Reitz has been good and bad at times. And while things of his are genius level, he also has done asshole level things. But on the other hand, we get that with a lot of geniuses for some reason or another. Really smart people can be really dumb too.
It would be like saying, "Don't use Laplace transforms because he did some unsavory thing at some point in time."
Looking at this drama for a bit, I haven't seen anybody advocate for 'canceling' requests itself.
Maybe it's more like: Laplace created awesome things, but let's be fair and also put in his wikipedia page a bit about his political shenanigans.
A lot of of so-called geniuses, especially the self-styled ones with some narcissistic traits, get away with being an asshole. Their admirers have different norms for regular, boring people. I don't think that is fair or healthy for a community.
Back when the drama was fresh, there was a lot of talk about “canceling” Requests, but as often happens, everyone moved o to something else and it kinda got forgotten about with time.
It stopped accepting new features a decade ago, it doesn’t support HTTP/2, let alone HTTP/3, it doesn’t support async, and the maintainers ignored the latest security vulnerability for eight months.
It was good when it was new but it’s dangerously unmaintained today and nobody should be using it any more. Use niquests, httpx, or aiohttp. Niquests has a compatible API if you need a drop-in replacement.
Me, because nearly every time I see it used, it’s for a trivial request or two that can easily be handled with stdlib.
If you need it, sure, it’s great, but let’s not encourage pulling in 3rd party libs unnecessarily.
Strong agree. Pip doesn't really need Requests' functionality as far as I can tell, but the vendored transitive dependencies represent a considerable fraction (something like a quarter IIRC) of Pip's bulk. And a big fraction of that bulk (and it's much the same for Rich) at startup, even if ultimately it turns out that no web requests need to be made. Which in turn is the main reason why Pip on my machine takes longer than the https://lawsofux.com/doherty-threshold/ to process `pip install` with no actual package specified. (A process that involves importing more than five hundred Python modules, of which almost a hundred are Requests and its dependencies.)
(Of the non-Requests imports, about two thirds of them occur before Pip even considers what's on the command line — which means that they will be repeated when you use the `--python` option. Of course, Requests isn't to blame for that, but it drives home the point about keeping dependencies under control.)
I've noticed that Claude Code prefers httpx because it's typed.
I really like httpx’s handling of clients/sessions; it’s super easy to throw one in a context manager and then get multiple hits to the same server all reusing one http2 connection.
Weird! I have the opposite: I want it to prefer httpx but it always gives me Requests when I forget to specify it.
LLMs are funny.
> Save that as script.py and you can use "uv run script.py" to run it with the specified dependencies,
Be aware that uv will create a full copy of that environment for each script by default. Depending on your number of scripts, this could become wasteful really fast. There is a flag "--link-mode symlink" which will link the dependencies from the cache. I'm not sure why this isn't the default, or which disadvantages this has, but so far it's working fine for me, and saved me several gigabytes of storage.
>There is a flag "--link-mode symlink" which will link the dependencies from the cache. I'm not sure why this isn't the default
The hard-link strategy still saves disk space — although not as much (see other replies and discussion).
Possible reasons not to symlink that I can think of:
* stack traces in uncaught exceptions might be wonky (I haven't tried it)
* it presumably adds a tiny hit to imports from Python, but I find it hard to imagine anyone caring
* with the hard-linking strategy, you can purge the cache (perhaps accidentally?) without affecting existing environments
By default it will create hard links for python packages, so it won't consume any more memory (besides the small overhead of hard links).
As far as I can tell, this only applies to the wheel contents, not to the .pyc bytecode cache created by the interpreter. If you use the defaults, Python will just create per-environment copies on demand; if you precompile with `--compile-bytecode`, uv will put the results directly in the installed copy rather than caching them and hard-linking from there.
I plan on offering this kind of cached precompiled bytecode in PAPER, but I know that compiled bytecode includes absolute paths (used for displaying stack traces) that will presumably then refer to the cached copies. I'll want to test as best I can that this doesn't break anything more subtle.
Unless it can't because you happen to have mounted your user cache directory from a different volume in an attempt to debloat your hourly backups.
... your hourly backups aren't also using the same hard-linking strategy?
They’re ZFS snapshots, so no. That’s why I’m forced to keep my cache directory in a different dataset.
Ironically, if my backup scheme were using hard links, then I could simply exclude the cache directory from backup, so I’d have no reason to do that mountpoint spiel, and uv’s hard links would work normally.
... ZFS snapshots don't produce copies of the underlying file data, do they? (Yeah, I'm still a dinosaur on ext4...)
Nothing wrong with ext4! Having choices and preferences is a good thing.
You’re correct, ZFS snapshots don’t produce copies, at least not at the time they’re being created. They work a little like copy-on-write.
This is cool!
This gave me the questionable idea of doing the same sort of thing for Go: https://github.com/imjasonh/gos
(Not necessarily endorsing, I was just curious to see how it would go, and it worked out okay!)
That's fun. I gave this a try myself. I took a different approach to the solution and used a bash script.
https://gist.github.com/JetSetIlly/97846331a8666e950fc33af9c...
My question is: if you already have to put the "import" there, why not have a PEP to specify the version in that same import statement, and let `uv` scan that dependency? It's something I never understood.
This is addressed in detail the relevant ecosystem-wide standard: https://peps.python.org/pep-0723/#why-not-infer-the-requirem...
My own take:
PEP 723 had a deliberate goal of not making extra work for core devs, and not requiring tools to parse Python code. Note that if you put inline comments on the import lines, that wouldn't affect core devs, but would still complicate matters for tools. Python's import statement is just another statement that occurs at runtime and can appear anywhere in the code.
Besides that, trying to associate version numbers with the imported module is a complete non-starter. Version numbers belong to the distributions[1], which may define zero or more top-level packages. The distribution name may be completely independent from the names of what is imported, and need not even be a valid identifier (there is a standard normalization process, but that still allows your distribution's name to start with a digit, for example).
[1]: You say "packages", but I'm trying to avoid the unfortunate overloading the term. PyPA recommends (https://packaging.python.org/en/latest/discussions/distribut...) "distribution package" for what you download from PyPI, and "import package" for what you import in the code; I think this is a bit unwieldy.
They don't want tools like uv to have to parse Python, which is complex and constantly changes.
See also https://peps.python.org/pep-0723/#why-not-infer-the-requirem...
Ahh thanks for that! Makes sense, since you could also have an import somewhere down the script (although that would be bad design).
Another point is the ambiguous naming when having several packages doing roughly the same... Which is crucial here. Thank you! :)
This is cool, but honestly I wish it was builtin language syntax not a magic comment, magic comments are kind of ugly. Maybe some day…
(I realise there are some architectural issues with making it built-in syntax-magic comments are easier for external tools to parse, whereas the Python core has very limited knowledge of packaging and dependencies… still, one of these days…)
It IS built-in language syntax. It's defined in the PEP, that's built-in. It's syntax:
"Any Python script may have top-level comment blocks that MUST start with the line # /// TYPE where TYPE determines how to process the content. That is: a single #, followed by a single space, followed by three forward slashes, followed by a single space, followed by the type of metadata. Block MUST end with the line # ///. That is: a single #, followed by a single space, followed by three forward slashes. The TYPE MUST only consist of ASCII letters, numbers and hyphens."
That's the syntax.
Built-in language syntax.
Suppose I have such a begin block without the correct corresponding end block - will Python itself give me a syntax error, or will it just ignore it?
It might be “built-in syntax” from a specification viewpoint, but does CPython itself know anything about it? Does CPython’s parser reject scripts which violate this specification?
And even if CPython does know about it (or comes to do so in the future), the fact that it looks like a comment makes its status as “built-in syntax” non-obvious to the uninitiated
Semantic whitespace was bad enough, now we have semantic comment blocks?
I'm mostly joking, but normally when people say language syntax they mean something outside a comment block.
Shebang lines are semantic comments too
Not necessarily-while many languages which accept shebangs use hash as a line comment introducer, others don’t, but nonetheless will accept a shebang at the start of a file only. e.g. some Lisp interpreters will ignore the first line of a source file if it starts with #!, but otherwise don’t accept # as comment syntax.
I am - while awesomely valuing uv - also with the part of the audience wondering/wishing this capability were a language feature.-
The PEP explains why it isn't part of the regular python syntax.
uv and other tools would be forced to implement a full Python parser. And since the language changes they would need to update their parser when the language changes.
This approach doesn't have that problem.
Making it a "language feature" has no upside and lots of downside. As the PEP explains.
Beyond that, the needed name to download from PyPI doesn't necessarily have anything at all to do with the name used for an `import` statement. And a given PyPI download may satisfy multiple `import` statements. And it can even be possible to require a download from PyPI that doesn't install any importable code (it may legally be a meta-package that runs one-shot configuration code when "built from source").
Funny how all this time, the only commonly-used import syntax like this was in HTML+JS with the <script> tag.
I hope it's in the same format as requirements files. Because then one could put a comment with a one liner next to it for people who don't have uv.
Something like `pip install -r <(head myscript.py)`. (Not exactly, but you get the idea).
uv is so cool. haha. goodbye conda.
conda is a completely no-go for me. It’s for data scientists, and only data scientists who do not need to care much about production.
Sadly this isn't always true, if you have non-pure Python dependencies, you might still need to use conda since they package database drivers or complex C/C++ dependencies for example.
SciPy already provides pip-installable wheels for a wide variety of platforms: https://pypi.org/project/scipy/#files
One gotcha I caught myself in with this technique is using it in a script that would remediate a situation where my home has lost internet and needed the router to be power cycled. When the internet is out, `uv` cannot download the dependencies specified in the script, and the script would fail. Thankfully I noticed this problem after writing it but before needing it to actually work, and refactored my setup to pre-install the needed dependencies. But don't make the same mistake I almost made! Don't use this for code that may need to run airgapped! Even with uv caching you may still get a cache miss.
`uv run --offline` will use cached dependencies and not check for newer versions. Works for `uvx` too, i.e. `uvx --offline ...`.
But don't you have to only ever run it once to have the deps/venv for subsequent runs?
I don't know if uv garbage collects its cache, but it wouldn't surprise me. Otherwise disk usage would grow indefinitely.
If you indefinitely grow the collection of packages that you have in use in permanent virtual environments, then yes your disk usage will and should grow indefinitely anyway.
There's not much point recycling contents from a package cache unless you currently don't have a venv using that package and also don't reasonably expect to have one in the near future.
And I'm saying this as the guy complaining all the time about things like the size of Numpy wheels.
Here's a fun one (says he, in a panic): Will we get to a point where (through fault or, gasp, design) a given AI will generatively code a missing dependency, on the fly - perhaps as a "last ditch" effort?
(I can imagine languages having official LLMs which would more or less "compress/know" enough of the language to be an ...
... import of last resort, of sorts, by virtue of which an approximation to the missing code would be provided.-
I'm pretty sure we've already reached a point where people generatively code possibly-malicious packages to publish under names of non-existent packages commonly hallucinated by LLMs prompted by other devs.
I love this feature of uv but getting linters/language servers to pick up the venv when editing the files is a bit of a pain. I currently have a script 'uv-edit' which I am using to run Neovim with the correct environment:
#!/bin/bash
SCRIPT="$1"; shift
uv sync --quiet --script "$SCRIPT" && exec uv run --python "$(uv python find --script "$SCRIPT")" nvim "$SCRIPT" "$@"This is my absolute favourite uv features and the reason I switched to uv.
I have a bunch of scripts in my git-hooks which have dependencies which I don't want in my main venv.
#!/usr/bin/env -S uv run --script --python 3.13
This single feature meant that I could use the dependencies without making its own venv, but just include "brew install uv" as instructions to the devs.
If I may interject, does anyone have any idea why the `-S` flag is required? Testing this out on my machine with a BSD env, `/usr/bin/env -S uv run --python 3.11 python` and `/usr/bin/env uv run --python 3.11 python` do the same thing (launch a Python interactive shell). Man page for env doesn't clarify a lot to me, as the end result still seems to be the same("Split apart the given string into multiple strings, and process each of the resulting strings as separate arguments to the env utility...")
Its needed on my ubuntu 24.04 system
$ cat test.sh
#!/usr/bin/env bash -c "echo hello"
$ ./test.sh
/usr/bin/env: ‘bash -c "echo hello"’: No such file or directory
/usr/bin/env: use -[v]S to pass options in shebang lines
$ ./test.sh # with -S
helloInteresting, I guess it is indeed a BSD thing, cause this works for me with or without '-S' on Mac
There currently is a patch for adding '-S' to OpenBSD and in the discussion, the one who came originally up with it commented on how he added it to FreeBSD:
"IIRC, the catalyst for it was that early FreeBSD (1990's?) did split up the words on the '#!' line because that seemed convenient. Years later, someone else noticed that this behavior did not match '#!' processing on any other unix, so they changed the behavior so it would match. Someone else then thought that was a bug, because they had scripts which depended on the earlier behavior. I forget how many times the behavior of '#!' processing bounced back and forth, but I had some scripts which ran on multiple versions of Unix and one of these commits broke one of those scripts.
I read up on all the commit-log history, and fixed '#!' processing one more time so that it matched how other unixes do it, and I think I also left comments in the code for that processing to document that "Yes, '#!'-parsing is really supposed to work this way".
And then in an effort to help those people who depended on the earlier behavior, I implemented '-S' to the 'env' command.
I have no idea how much '-S' is used, but it's been in FreeBSD since June 2005, and somewhere along the line those changes were picked up by MacOS 10. The only linux I work on is RHEL, and it looks like Redhat added '-S' between RHEL7 and RHEL8." [https://marc.info/?l=openbsd-tech&m=175307781323403&w=2]
FWIW, GNU Coreutils env (as seen for example in my Linux Mint distribution) works the same way (no split by default, enabled by `-S`) and I definitely have used it locally to do things like `#!/usr/bin/env -S python -S -I`.
Thanks, but the main question is how come the behaviour is still the same whether you pass the flag or not? I would get it if it just failed without "-S" but it works as intended. I am wondering if this is cause I might not be using the GNU version of env, so this is less relevant? Edit: looks to be the version thing indeed, this doesn't work for someone on Ubuntu
At some point coreutils added -S in order to support the behavior of BSD and MacOS. I would guess that whatever implementation you're using then added -S as a noop in order to (at long last) permit the portable usage of multi-argument shebang lines. Until both of those things happened there was no portable way to pass multiple arguments in a shebang. You used to have to do really stupid things (ex https://unix.stackexchange.com/a/399698).
https://www.gnu.org/software/coreutils/manual/html_node/env-...
Actually, you might be onto something! If I test with explicit quoting in terminal, BSD and GNU produce the same behavior:(`env 'bash -c "echo hello"'` fails while `env -S 'bash -c "echo hello"'`) works. I wasn't aware of this:
"To test env -S on the command line, use single quotes for the -S string to emulate a single parameter. Single quotes are not needed when using env -S in a shebang line on the first line of a script (the operating system already treats it as one argument)"(from your second link).
This is different for shebang on Mac though:
GNU env works with or without '-S':
#!/opt/homebrew/bin/genv -S bash -v
echo "hello world!"
BSD env works with or without '-S' too:
#!/usr/bin/env -S bash -v
echo "hello world!"
To conclude, looks like adding `-S` is the safest option for comparability sake :).
Completely agree. UV for stalled what was going to be a major project to move lots of python to golang. There will still be a lot migrated, but smaller script like things are no longer in scope.
I still write small some scripts in golang when the bootup time is important. Python still takes its time to boot up, and it's not the best tool for the job if it's gonna be called like a shell utility for thousands of files, for example.
All my "permanent" scripts were transferred to Go a while ago with LLM assistance.
They're the ones that just keep running in cron with zero modifications.
Python is when I need to iterate fast and just edit crap on the go, most of those will also be migrated to Go after they stabilise - unless there's a library dependency that prevents it.
`uv` is nice, but it's not "static binary that runs literally anywhere with no prerequisites" -nice
I've been doing something similiar utilizing guix shell[0] setting my shebang to e.g.:
#!/usr/bin/env -S guix shell python python-requests python-pandas -- python3
in scripts for including per-script dependencies. This is language agnostic as long as the interpreter and its dependencies are available as guix packages. I think there may be a similiar approach for utilizing nix shells that way as well.
[0]: https://guix.gnu.org/manual/en/html_node/Invoking-guix-shell...
Do these environments reuse existing system-installed packages and hard-link the files?
I wish there was a straightforward way to let VS Code pick up the venv that uv transparently creates.
Out of the box, the Python extension redlines all the third-party imports.
As a workaround, I have to plunge into the guts of uv's Cache directory to tell VS Code the cached venv path manually, and cross fingers that it won't recreate that venv too often.
You can find the env path with `uv python find --script "${filePath}`
I've been working on a VSCode extension to automatically detect and activate the right interpreter: https://marketplace.visualstudio.com/items?itemName=nsarrazi...
Could you tell me how you do this in code ? Started using uv in a very old school team and they don’t like uv simply because it’s new. Something like this is what they base it on.
It's super cumbersome so I can't really recommend it for work.
I invoke the "Select Interpreter" action. A file selector opens, then I go to the user cache directory (e.g. ~/.cache on Linux, something like %LOCALAPPDATA%\Cache on Windows). It has a `uv` subdirectory, then I drill further down until I find the directory where uv keeps its venvs. Find the venv that corresponds to your script, then go to its `bin` subdirectory and select the Python executable.
The upside is that you only have to do this once per script.
The downside is that you have to do this once per script.
I also just activate the desired virtual env and start VS Code from the command line within it
Note that this only works for single-file scripts.
If you have a project with modules, and you'd like a module to declare its dependencies, this won't work. uv will only get those dependencies declared in the invoked file.
For a multi-file project, you must have a `pyproject.toml`, see https://docs.astral.sh/uv/guides/projects/#managing-dependen...
In both cases, the script/project writer can use `uv add <dependency>`, just in the single-file case they must add `--script`.
Love this feature of UV. Here's a one-liner to launch jupyter notebook without even "installing" it:
uv run --with jupyter jupyter notebook
Very nice. Here's a one liner for marimo notebooks:
uvx marimo edit
A one liner with marimo that also respects (and records) inline script metadata using uv:
uvx marimo edit --sandbox my_notebook.py
Note that it's not really "cleaned up" insofar as there is a uv cache folder that will grow bigger over time as you keep using that feature.
True. It's a good idea to periodically run:
uv cache clean
uv cache clean jupyterif anyone else is curious..
% cd $(uv cache dir); find . -type f | wc -l; du -hs .
234495
16G .I do this all the time as well with `uv run --with ipython --with boto3 ipython`. Great time-saver.
Oh nice, I was already a happy user of the uv-specific shebang with in-script dependencies, but the `uv lock --script example.py` command to create a lock file that is specific to one script takes it to another level! Amazing how this feels so natural and yet only appeared after 20+ years of Python packaging.
What’s your use case for locking dependencies on a single script?
One things that’s useful to my organization is that we can then proceed to scan the lockfile’s declared dependencies with, e.g., `trivy fs uv.lock` to make sure we’re not running code with known CVEs.
Just better visibility into the dependencies that come with the script (exactly for things like vulnerability scanning that you mention). It's also easier for reproducibility in someone else's environment when I can give them the exact list of dependencies instead of having them resolve it themselves using the inline declarations. Explicit is better than implicit :-)
There are a lot of bits and pieces that are clicking into place lately in the Python ecosystem. Recently I've been using the combination of Marimo and these uv script dependencies for building reproducible rwporting and diagnostic tooling for other teams.
As a tangent, one issue I face is how to force cursor to use uv over pip. I have placed it in rules and also explicitly add a rules.yml file in every agent conversation. It still tries to push through pip 4 out of 10 times. Any recommendations on best practice to force cursor to use uv will make a significant dent in productivity
more of a bandaid than anything else, but maybe something like this might help:
alias pip='echo "do not use pip, use uv instead" && false'
You can put that in your bashrc or zshrc. There's a way to detect if it's a cursor shell to only apply the alias in this case, but I can't remember how off the top of my head!
> alias pip='echo "do not use pip, use uv instead" && false'
Interesting times, eh?
Who (who!) would have told us all we'd be aliasing terminal commands to *natural language* instructions - for machine consumption, I means. Not for the dumb intern ...
(I am assuming that must have happened at some point - ie. having a verboten command echo "here be dragons" to the PFY ...)
Quick plug here for a simple Jupyter kernel I created:
https://github.com/tobinjones/uvkernel
It’s a pretty minimal wrapper around “uv” and “iPython” to provide the functionality from the article, but for Jupyter notebooks. It’s similar to other projects, but I think my implementation is the least intrusive and a good “citizen” of the Jupyter ecosystem.
There’s also this work-in-progress:
https://github.com/tobinjones/pep723widget
Which provides a companion Jupyter plugin to manage the embedded script dependencies of noteboooks with a UI. Warning — this one is partially vibe-coded and very early days.
There is also marimo. For my use cases it has been a fantastic upgrade from Jupyter. I use it in the style of TFA (notebooks are just Python files). In the notebook UI, you can add packages to the script headers. It's so nice to have many notebooks in one directory with independent, but reproducible environments.
Marimo notebooks are easy to diff when committing to git. Plus you get AI coding assistants in the notebook, a reactive UI framework, the ability to run in the browser with Pyodide on WASM, and more. It will also translate your old Jupyter notebooks for you.
For me, what uv is to package managers, marimo is to notebooks.
This is pretty great. Passing python code out to my students is usually also confronted with the question of "How do I run it?", which is usually terrible to answer. Now, I can just tell them to get uv (single command) and run it.
I do this in Swift, using swift-sh[1].
Works well, but the compilation of the dependencies (first run of the script) can be a bit long. A problem which uv (Python) probably won’t have…
If you’re at all interested in this topic, I strongly recommend you read Simon Willison’s blog at https://simonwillison.net/
He does all the legwork and boils it down into an easily-understandable manner.
He’s also a user her in this thread at simonw. Just an immensely useful guy.
How many package managers can one language have? Its a simple language but setting it up is just incredibly bad. Maybe this is the one or should I wait for the next?
I had the same sentiment, but uv seems to have eliminated the competition. Installing uv using your OS package manager is enough as it can also download and install (isolated) Python interpreters as well.
Except pip still exists and is default, and even if they adopted uv as default instead, all the legacy stuff takes years to change.
pip is not a package manager, it's only meant for installing packages. Also, uv has a pip-compliant interface through `uv pip` which lets you interface with pip easily.
Those shouldn't be separate things. uv is both. Anyway, the default package manager is pipenv https://packaging.python.org/en/latest/tutorials/managing-de...
> Its a simple language
No, it isn’t. This misconception is common and I don’t know where it comes from.
Python is a very complex language hiding behind friendly syntax.
I recommend trying it, it gets a ton of hype but I think for good reason.
This is the one.
imo all I usually need is pip-tools and venv, but uv kind of bundles the two together in a very natural way (and is very fast)
Unless you're installing a new version of python, I have trouble seeing how preceding all the normal command with "uv" can be seen as much of a difference.
It's not that much of a difference, but it is faster, and when you do need to switch pythons, you're already set up. uv also has some different workflows, universal lock files, and the caching is also nice. And the PEP 723 support is cool!
Poetry was a big difference, it was also very slow for me, and so I never picked it up.
Its a simple language
It really isn't, and that is why the install and setup tools are so problematic. They have to hide and overcome a lot of complexity.
I recently found a small issue with `uv run`. If you run a script from outside the project folder, it looks for the pyproject.toml on the folder from which you are calling `uv run`, not on the folder where the python script is located (or its parents)! Because of that scripts that store their dependencies in a pyproject.toml cannot be run successfully using a “bare” `uv run path/to/my/script.py` from outside the project folder.
You can work around this surprising behavior by always using inline dependencies, or by using the `--project` argument but this requires that you type the script path twice which is pretty inconvenient.
Other than that uv is awesome, but this small quirk is quite annoying.
Why doesn't pip support PEP 723? I'm all for spreading the love of our lord and savior uv, but it should be necessary to have an official implementation.
It's completely out of scope for pip, which is purely about modifying the set of packages installed into non-transient environments.
Pipx is a wrapper that does more or less what you're looking for (including PEP 723 support), but it arbitrarily refuses to process top-level packages unless they specify an entry point (which makes them "applications" even with abstract dependencies).
I'm planning to support it in PAPER, which can roughly be described as my vision of what pip and pipx, taken together, should have been.
I don't know if there's an official reason, but my guess is that it's slightly out of scope for pip: pip is a packaging installation tool, not a virtual environment managing system.
uv, being both, is a more natural fit for an implementation of that PEP.
Here's a relevant discussion: https://discuss.python.org/t/idea-introduce-standardize-proj...
This almost as great as how much I love that this gets posted like once every two weeks
I'm glad it was reposted so I saw it. I may actually use python for scripting now because uv makes it so easy.
I like it, and I once thought about this as well:
> Python doesn't require a requirements.txt file, but if you don't maintain this file, or neglect to provide one, it could result in broken functionalities - an unfortunate circumstance for a scripting language.
I kinda always struggled to grok python's package management and module system. UV is finally making things more understandable and just as good as the nodejs packaging and module system that I'm more comfortable with. This new feature is kinda awesome. Even surpassing the DX of the node ecosystem.
Maybe worth mentioning that ruby has a very similar feature https://bundler.io/guides/bundler_in_a_single_file_ruby_scri...
I am using this feature in my MCP servers and it is a god send! Some details on how I do it can be found at https://blog.toolkami.com/toolkami-shttp-server/.
There's a lot of small one off things where deploying uv and the script makes it easy to use. A lot of use cases for golang can be replaced with uv.
Oh this looks amazing! I had pretty much stopped using Python for my one-off scripts because of the hassle of dependencies. I can't wait to try this out.
I've played with it for a while now, and for one off scripts where python might make more sense than bash, e.g., I write the script this way with uv, and then I only need uv and the script.
One of the complaints about python is that a script stops working over time (because the python installation changes with os updates), and this kinda sorta doesn't make it go away entirely, but what it does do is to eliminate a bunch of the hassle to getting things to work.
> this kinda sorta doesn't make it go away entirely
it absolutely can, `uv` can also pin the python interpreter it uses with `requires-python = "==3.11"` or whatever.
Am I crazy for having my default interactive shell "/bin/env python" point to a virtual environment with all the random dependencies that my one off scripts need, so I can just run "python oneoneoff.py"? All of my one off scripts combined use maybe a dozen dependencies. If I need more, I just install them there. I use pyenv, so it's trivial to change the version of python that the interactive shell uses (default or temporary within the current shell).
From my perspective, people seem to make it difficult to use python, more from not understanding the difference between interactive shell and non-interactive shell configurations (if you think the above breaks system tools that use python, then you don't understand the difference, nor that system tools use /bin/python rather than /usr/env python), with a bit of cargo-cult mixed in, more than anything.
What would you do if some of the deps started to have conflicts in them? Also, what are your plans for migration when you'll need to move from one os version to another?
Implicit solutions like yours have lower cost of entrance, but larger cost of support. uv python scripts just work if you set them up once
https://docs.astral.sh/uv/guides/scripts/#declaring-script-d...
this is neat af. my throw-away scripts folder will be cleaner now.
My favorite part of this is the `exclude-newer` feature, giving you a somewhat reproducible script for very low effort.
One case this may not work well is when one of the dependencies is Pytorch. Uv has explicit support for Pytorch ( https://docs.astral.sh/uv/guides/integration/pytorch/ ) but with the script headers I don't see a way to pick the most appropriate wheel index (cpu vs cuda vs rocm)
I just looked this up yesterday by sheer coincidence and was happy it actually worked. What brought it to your attention today?
Almost certainly the thread about jqfmt: https://news.ycombinator.com/item?id=44637716
Heard about this! Finally did something with it and I'm happy with how this tiny gist turned out:
https://gist.github.com/pythoninthegrass/e5b0e23041fe3352666...
tl;dr
Installs 3 deps into the uv cache, then does the following:
1. httpx to call get request from github api
2. sh (library) to run ls command for current directory
3. python-decouple to read an .env file or env var
For this use case I would try first to compile the script with nuitka. A single binary is more manageable than doing that
As a non-Python person, I find “uv” to be a confusing name.
For a long time I assumed it’s a Python wrapper for libuv which is a much older and well-known project. But apparently it’s Python package manager #137 “this one finally works, really, believe me”
I hate such poor docs that don't explain how things work, and instead prefer hiding behind some "magic".
> Constraints can be added to the requested dependency if specific versions are needed:
> uv run --with 'rich>12,<13' example.py
Why not mention that this will make uv download specified versions of specified packages somewhere on the disk. Where? Are those packages going to get cached somewhere? Or will it re-download those same packages again and again every time you run this command?
Caching linked on the left: https://docs.astral.sh/uv/concepts/cache/ The index of the Concepts section says: "Looking for a quick introduction to features? See the guides instead."
Maybe there should instead be a link to the Concepts section for people who want more details, but I feel it's fine as it is.
Uh oh. I am thinking all the ways this can be misused to ship malicious dependencies. Pretty much all SCA tools today will be blind to this.
More comments the topic - https://news.ycombinator.com/item?id=44369388
Fun with uv and PEP 723
640 points | 227 comments
This is pretty easy to do if you have Nix
https://github.com/pmarreck/yt-transcriber
A commandline youtube transcription tool I built that runs on Mac (nix-darwin) which automatically pulls in all the dependencies it needs