Knowledge Base

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Single-File Dependency Management in Python Script Using UV ======

Make sure you already have [[https://docs.astral.sh/uv/getting-started/installation/|uv installed]].)

I don’t have Numpy installed globally, so we’ll use that in our example script. Create a file named ''numpy_version.py'' with the following contents:

<file python numpy_version.py>
import numpy as np

def show_numpy_version():
    print(np.__version__)

if __name__ == '__main__':
    show_numpy_version()
</file>

If we try to run it as-is (''python3 numpy_version.py'') we see this:

<code>
Traceback (most recent call last):
  File "numpy_version.py", line 1, in <module>
    import numpy as np
ModuleNotFoundError: No module named 'numpy'
</code>

We can use uv to add inline metadata declaring the dependencies:

<code bash>
uv add --script numpy_version.py numpy
</code>

The script will be updated to look like this:

<file python numpy_version.py>
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "numpy",
# ]
# ///
import numpy as np

def show_numpy_version():
    print(np.__version__)

if __name__ == '__main__':
    show_numpy_version()
</file>

Then, we use uv to run it:

<code bash>
uv run numpy_version.py
</code>

And we get this output:

<code>
Reading inline script metadata from `numpy_version.py`
2.2.1
</code>

We can make our script directly runnable by adding a shebang line at the top of the file:

<code python>
#!/usr/bin/env -S uv run -q -s
</code>

…and making the script executable:

<code bash>
chmod u+x numpy_version.py
</code>

<WRAP center round important 60%>
The -S argument to env is required in order for the run argument to be handled correctly.
</WRAP>

Now we can run the script as ''./numpy_version.py''.

When we run the script like this, uv automatically manages the dependencies in an isolated environment. We can test this by trying to run the updated script directly with Python again:

<code bash>
python3 numpy_version.py
</code>

We get this, indicating that in a global context Numpy is still not installed:

<code>
Traceback (most recent call last):
  File "numpy_version.py", line 10, in <module>
    import numpy as np
ModuleNotFoundError: No module named 'numpy'
</code>

Our end result is a nice, clean, directly runnable, isolated script whose only execution requirement is that uv be installed.

The portability that this provides is really nice. I installed uv on a [[https://libre.computer/products/aml-s905x-cc/|Le Potato]] and I was able to immediately run my script on the device with no changes. UV even automatically installed a CPython version to meet the Python version requirement. (The inline metadata specifies a Python version >= 3.12, but the global Python interpreter on the SBC is 3.11)

{{tag>python}}