PengyOS / Docs / Recipes / Python with uv

Python with uv

Server and Desktop come with Python 3.14 and pip. uv adds everything else: per-project environments, any other Python version, and isolated command-line tools. It runs right on the host and keeps everything in your home directory.

ServerDesktop

Install uv

mkdir -p ~/.local/bin
curl -LsSf https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-unknown-linux-gnu.tar.gz \
  | gzip -dc | tar -xf - -C ~/.local/bin --strip-components=1
uv --version

From PengyOS 26.10.0, uv's own one-liner works too: curl -LsSf https://astral.sh/uv/install.sh | sh. On older releases it fails (they lack ldd and GNU tar). The lines above work on every release. Upgrade later with uv self update.

A project

uv init hello && cd hello      # pyproject.toml, .python-version, main.py
uv add requests numpy          # dependencies go in pyproject.toml + uv.lock
uv run python main.py          # runs in the project's .venv (created on demand)
uv run pytest                  # any tool in the environment

Commit pyproject.toml and uv.lock. uv sync rebuilds the exact environment on another machine.

Another Python version

uv downloads standalone CPython builds that run fine on PengyOS:

uv python install 3.12
uv init --python 3.12 legacy-app         # a project pinned to 3.12
uv venv --python 3.12 ~/venvs/py312     # or a plain virtual environment
uv run --no-project --python 3.12 python   # a quick 3.12 prompt

Command-line tools

Each tool gets its own environment, and its command goes into ~/.local/bin:

uv tool install ruff
uv tool install podman-compose
uv tool install httpie
uv tool list
uv tool upgrade --all
uvx black --check .           # run once without installing

When a package needs a compiler

Most popular packages (numpy, pandas, cryptography, pydantic, psycopg's binary build…) ship prebuilt wheels and install on the host. A package that only ships source, or an old version without wheels for your Python, needs a C compiler and fails on the host with Failed to build. Do that project in the dev box, where uv is already installed and gcc is a sudo apt install away:

pengyos-guest enter dev -- sh -c 'cd ~/src/myproject && uv sync'

The .venv it creates lives in your shared home. It's built against the box's libraries, though, so run it in the box too.

Browser automation (Playwright)

Playwright downloads browsers built for Ubuntu, and they need a desktop's worth of Ubuntu libraries. On the PengyOS host the browser won't start (error while loading shared libraries: libnspr4.so, and more after that). Use the dev box, where Playwright installs what it needs with apt:

pengyos-guest enter dev
mkdir -p ~/src/scraper && cd ~/src/scraper
uv init && uv add playwright
uv run playwright install --with-deps chromium     # browser + its Ubuntu libraries
uv run python main.py

The browsers are cached in your home (~/.cache/ms-playwright), so they survive a rebuilt box, but the libraries don't: run playwright install --with-deps again after rebuilding it. Headless runs need nothing else. A visible browser window works too, because the box shares your display.

Plain pip

python3 -m venv and pip work as usual, but install into a virtual environment rather than the system Python. The system Python is part of the read-only image.

python3 -m venv ~/venvs/tools && ~/venvs/tools/bin/pip install requests
← Containers with podmanRust with rustup →