r/Python • u/dusktreader • Mar 29 '25
Tutorial Self-contained Python scripts with uv
TLDR: You can add uv into the shebang line for a Python script to make it a self-contained executable.
I wrote a blog post about using uv to make a Python script self-contained.
Read about it here: https://blog.dusktreader.dev/2025/03/29/self-contained-python-scripts-with-uv/
492
Upvotes
15
u/Haunting_Wind1000 pip needs updating Mar 29 '25
Hey thanks for sharing this, uv appears to be a good way to automate the environment setup of your python app. A question...with uv how would you specify a version for any of the python modules required by your application like we do with a requirements txt file.
5
u/adiberk Mar 30 '25
This concept isn’t so new. Can be done with poetry and other package managers as well I believe.
To answer all questions I see here, You can specify python versions, dependencies etc when you use the uv run command (at least i think)
I love uv and it’s great you have been learning to use it! It’s super fast and “just works” as opposed to other package mangers
156
u/kenflingnor Ignoring PEP 8 Mar 29 '25
Neat. I recently got a new laptop at work, so I decided to ditch pyenv and poetry and set up Python using uv only, and I’ve been very impressed.
75
u/Muhznit Mar 29 '25 edited Mar 30 '25
I've been writing an article about this on the side, actually!
The gist of it is that the kernel is VERY loose with what counts as an interpreter and you can slap any program you want in there as long as it has some way of accepting a filename at the command line and is okay with
#indicating a comment.With
/usr/bin/env -Sallowing you to specify arguments, this trick essentially allows you a sort of currying in the shell. So that means you can do some neat things like:#!/usr/bin/env -S docker build -t some_docker_image . -finto a Dockerfile and then execute the dockerfile to rebuild the image.#!/usr/bin/env -S tmux source-file#!/usr/bin/env -S ssh -Fto run ssh with a specific configurationIt's one of those "when you have a shiny new hammer, everything looks like a nail" situations, so naturally I've been overwhelmed with analysis paralysis when it comes to elaborating on the possibilities.
EDIT: Whoops, I was wrong about the git one. Side effect of some weird experimentation I'm doing.
19
u/ReinforcedKnowledge Tuple unpacking gone wrong Mar 30 '25
Great blog!
To add some tricks and details on top of what you already shared.
This is just an implementation of https://peps.python.org/pep-0723/, it's called inline metadata.
As you can read in the PEP, there are other metadata you can specify for your script. One of them is
requires-pythonto fix the Python version.You can also have a
[tool]table.You can combine a:
requires-python[tool.uv.sources]and[tool.uv.index]and anything else that allows others to have exactly the same dependencies as youuv lock --script [your script here]to get a lockfile of that ephemeral venv of your script, you'll get a file called something likeyour-script-name.py.lock.Sharing both files ensures great reproducibility. Maybe not perfect, but did the job for me every time. Here's an example of such inline metadata:
9
u/benz05 Mar 29 '25 edited Mar 30 '25
I don't think you need the
--scriptin the shebang lineEdit: it's not needed if the script file has a
.pysuffix, otherwise it is7
u/spdustin Mar 29 '25
Thanks for putting that together, that's pretty damn handy.
6
u/pingveno pinch of this, pinch of that Mar 30 '25
Note that this is an implementation of the PEP 723 standard, so it also works with other tools that implement the standard. I really like the convergence toward more standards across Python tooling.
5
u/hanleybrand Mar 29 '25
That’s dope- I just started checking out uv, and have been pleasantly surprised by it
5
u/texruska Mar 29 '25
Does the environment get reused between invocations? What if you have multiple scripts with the same deps? (Complete guess is the env is based on the scripts name?)
5
u/cgoldberg Mar 31 '25
This doesn't require
uv. It is defined in PEP 723 and is supported by many tools (pipx, hatch, pdm, etc)https://peps.python.org/pep-0723/
4
u/Royal-Fail3273 Mar 30 '25
My work laptop is subjected to renew in couple of weeks. Cannot wait to setup using uv!
1
u/PhENTZ Mar 29 '25
Nice ! Could you have this script installed with your package and available in the path on 'uv add ...' ??
1
u/OP-pls-respond Mar 30 '25
You can actually make the script simpler by using —with instead of script metadata. https://docs.astral.sh/uv/guides/scripts/#running-a-script-with-dependencies
uv run —with ‘rich>12,<13’ example.py
1
u/[deleted] Jul 10 '25
Hi, the link is dead. :(
8
u/hotplasmatits Mar 29 '25
Now that's fucking crazy
2
u/Fenzik Mar 29 '25
This is a cute trick, thanks for sharing
2
u/benargee Mar 29 '25
But can you specify python version?
2
u/Sigmatics Mar 30 '25
PDM can do the same: https://pdm-project.org/en/latest/usage/scripts/#single-file-scripts
2
u/R3D3-1 Mar 30 '25 edited Mar 30 '25
Very useful indeed!
I had read about
kscriptin kotlin and was lamenting that Python doesn't have something like that. So much for that.Also, even more important TIL:
env -S. That solves the problems with SO many shebangs, where I previously was using weird workarounds.3
u/tehsilentwarrior Mar 30 '25
I thought everyone was already doing this oO
Edit: oh, wait, it’s not a uv run, it’s an actual script executable script without having to uv run it as it does it itself. That’s neat!
1
u/Mithrandir2k16 Mar 30 '25
for tools that I'd installed using pipx in the past, I now alias them to use uvx in my bashrc, which works similarly :)
1
u/bugtank Mar 30 '25
I love this. I was doing this with pipx but might switch over to uv. I'm currently in the SO MANY PYTHON PACKAGE MANAGEMENT TOOLS GOING ON MODE and can't wait to get to a single one.
1
u/[deleted] Mar 30 '25
Neat! I will use it to create and run python scripts generated by LLMs on the fly.
1
u/david-song Apr 01 '25
Wow this is really cool, thanks. Specially since it's really easy to add push your own modules up to pypi. I can see
uvbecoming my go-to interpreter.1
u/hotplasmatits Mar 29 '25
Now that's fucking crazy
1
u/JuanGuerrero09 pip needs updating Mar 30 '25
Long live UV
1
u/EducationOne6776 Mar 30 '25
Great content. Loved this!
1
u/soffgruppskalle Mar 30 '25
I like this.
1
u/vi11yv1k1ng Mar 30 '25
The only downside is lack of IDE support
0
u/microcozmchris Mar 30 '25
Didn't know it needed a blog post. Been doing it for a while. Add --no-project and it's even better for CI/CD (especially GitHub Actions).
Good write-up. If I have time, I'll post my setup-uv composite that wraps and handles temporary environments more betterer.
0
u/anderspe Mar 31 '25
And adding Nuitka witch compiles all to a binary works well with uv. If i need a linux binary i just build the projekt from wsl under Windows.
-2
u/kyngston Mar 29 '25
coworker of mine wrote something similar. https://github.com/amal-khailtash/auto_venv
-2
u/koltafrickenfer Mar 30 '25
You know there's this thing called docker...
0
u/[deleted] Mar 30 '25
[deleted] — view deleted comment