View source for Python quickstart using uv


This tutorial shows the most straightforward way to install and use [https://github.com/astral-sh/uv uv] with Python on NixOS. It covers installation, project initialization, adding dependencies, and handling the most common error.

It is also important to note that, as mentioned in the [[Python#using_uv]] article, '''you do not need to install Python as a system package''', and you can instead install it through uv itself.

You can find more information regarding uv and how it works in the [https://docs.astral.sh/uv/concepts/projects/ uv documentation], 

== Install uv ==
Add uv to your system packages in <code>/etc/nixos/configuration.nix</code>:<syntaxhighlight lang="nix">
environment.systemPackages = with pkgs; [
  uv
];
</syntaxhighlight>Then rebuild:<syntaxhighlight lang="bash">
sudo nixos-rebuild switch
</syntaxhighlight>

== Initialize a Project ==
Navigate to your project directory and run:<syntaxhighlight lang="bash">
uv init
</syntaxhighlight>This, among other files for your project, creates a <code>pyproject.toml</code> file to place your dependencies into.

== Add Dependencies ==
Add dependencies to your <code>pyproject.toml</code>, for example:<syntaxhighlight lang="toml" start="1">
[project]
name = "example"
version = "0.1.0"
requires-python = ">=3.13,<=3.14"

dependencies = [
   "playwright>=1.54.0,<2.0.0",
   
]
</syntaxhighlight>

== Sync Dependencies ==
Run:<syntaxhighlight lang="bash">
uv sync
</syntaxhighlight>

=== Common Error ===
On NixOS, you may see this error:<pre>error: Querying Python at `/home/<user>/.local/share/uv/python/cpython-3.13.5-linux-x86_64-gnu/bin/python3.13` failed with exit status exit status: 127

[stderr]
Could not start dynamically linked executable: /home/<user>/.local/share/uv/python/cpython-3.13.5-linux-x86_64-gnu/bin/python3.13
NixOS cannot run dynamically linked executables intended for generic
linux environments out of the box. For more information, see:
https://nix.dev/permalink/stub-ld</pre>This happens because "NixOS cannot run dynamically linked executables intended for generic Linux environments out of the box."<ref>https://nix.dev/guides/faq#how-to-run-non-nix-executables</ref>

== Fix with nix-ld ==
The quickest solution is to enable [https://wiki.nixos.org/wiki/Nix-ld nix-ld] In your <code>/etc/nixos/configuration.nix</code>, add:<syntaxhighlight lang="nix">
programs.nix-ld.enable = true;
</syntaxhighlight>Then rebuild:<syntaxhighlight lang="bash">
sudo nixos-rebuild switch
</syntaxhighlight>After this, <code>uv sync</code> will work correctly.

'''You now have a working uv setup with Python on NixOS.'''

== See also ==
<references />
[[Category:Tutorial]]
[[Category:Python]]
[[Category:Uv]]
[[Category:Configuration]]