Python quickstart using uv
Tutorial: Quickstart with uv for Python on NixOS
This guide shows the fastest way to install and use 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 uv documentation,
Install uv
Add uv to your system packages in /etc/nixos/configuration.nix:
environment.systemPackages = with pkgs; [
uv
];
Then rebuild:
sudo nixos-rebuild switch
Initialize a Project
Navigate to your project directory and run:
uv init
This, among other files for your project, creates a pyproject.toml file to place your dependencies into.
Add Dependencies
Add dependencies to your pyproject.toml, for example:
[project]
name = "example"
version = "0.1.0"
requires-python = ">=3.13,<=3.14"
dependencies = [
"playwright>=1.54.0,<2.0.0",
]
Sync Dependencies
Run:
uv sync
Common Error
On NixOS, you may see this error:
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
This happens because "NixOS cannot run dynamically linked executables intended for generic Linux environments out of the box."[1]
Fix with nix-ld
The quickest solution is to enable nix-ld In your /etc/nixos/configuration.nix, add:
programs.nix-ld.enable = true;
Then rebuild:
sudo nixos-rebuild switch
After this, uv sync will work correctly.
You now have a working uv setup with Python on NixOS.