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