How to install uv on 32-bit Raspberry Pi OS

uv’s standalone installer works on 32-bit Raspberry Pi OS (armv7l), but three quirks bite first-time users: uv python install can fail to detect glibc on some Pi setups, PyPI rarely ships armv7l wheels, and a 32-bit userland running on a 64-bit kernel reports the wrong architecture. This guide walks through each so a 32-bit Pi install ends up in a working state.

For 64-bit Pi OS, the standard path applies; see How to run Python scripts on a Raspberry Pi with uv.

Confirm the architecture

Check what the Pi reports before installing:

uname -m

A 32-bit Raspberry Pi OS install prints armv7l (or armv6l on a Pi Zero W). A 64-bit install prints aarch64. The installer script reads uname -m and downloads the matching binary, so this is also the value uv will use to pick a release.

If the kernel is 64-bit but the userland is 32-bit, jump to Watch for 32-bit userland on a 64-bit kernel.

Install uv

The official standalone installer works on armv7l:

curl -LsSf https://astral.sh/uv/install.sh | sh

It downloads uv-armv7-unknown-linux-gnueabihf.tar.gz and writes the binary to ~/.local/bin/uv. Open a new shell and verify:

uv --version
uv self version --output-format json | grep -E '"(version|target)"'

The target field should read armv7-unknown-linux-gnueabihf. uv is a Tier 2 platform on armv7l Linux, so individual edge cases occasionally lag x86_64.

Fall back to system Python if uv python install errors out

python-build-standalone publishes armv7 builds, but uv’s libc detection has historically misidentified glibc-based ARM systems on some Pi setups (astral-sh/uv#6873, astral-sh/uv#17210). If uv python install errors out with a libc-related message, point uv at the system Python instead:

uv venv --python /usr/bin/python3

Raspberry Pi OS Bookworm ships Python 3.11 at /usr/bin/python3. That’s enough for most projects.

Configure piwheels for armv7l wheels

PyPI’s manylinux wheels target x86_64 and aarch64; many do not publish linux_armv7l builds. The piwheels project compiles armv7l wheels for the bulk of PyPI. Without it, uv falls back to building from source on the Pi, which is slow.

Configure uv to use piwheels as an extra index by writing this to ~/.config/uv/uv.toml:

[[index]]
name = "piwheels"
url = "https://www.piwheels.org/simple"

[[index]]
name = "pypi"
url = "https://pypi.org/simple"
default = true

uv queries piwheels first and falls back to PyPI when a package isn’t built there. The piwheels FAQ covers what’s built and how often. piwheels does not provide aarch64 wheels, so only configure this on 32-bit Pi OS.

Watch for 32-bit userland on a 64-bit kernel

A 32-bit Pi OS image booted with a 64-bit kernel (a configuration some Pi 4 owners run) reports aarch64 from uname -m but executes 32-bit binaries. uv reads the kernel arch and tries to install aarch64 wheels that the 32-bit userland cannot load. The open issue astral-sh/uv#9866 tracks the bug.

You can detect this case by checking what /usr/bin/python3 actually is:

file /usr/bin/python3

If it reports ELF 32-bit while uname -m says aarch64, you’re in the broken configuration. Two ways out:

1. Reflash with a true 64-bit Raspberry Pi OS image. This is the cleaner long-term fix.
2. Fall back to python3 -m pip install for the affected package. Standard pip reads the userland architecture and selects the correct armv7l wheel.

Learn More

• How to run Python scripts on a Raspberry Pi with uv covers the standard 64-bit Pi OS path.
• How to install uv on Linux covers shell completions and PATH troubleshooting that apply on Pi OS too.
• piwheels project hosts precompiled armv7l wheels for 32-bit Pi OS.
• uv platform support policy lists every architecture uv targets and the support tier for each.
• astral-sh/uv#9866 tracks the 32-bit userland on 64-bit kernel bug.