# 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](https://pydevtools.com/handbook/how-to/how-to-run-python-scripts-on-a-raspberry-pi-with-uv.md).

## Confirm the architecture

Check what the Pi reports before installing:

```bash
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](#watch-for-32-bit-userland-on-a-64-bit-kernel).

## Install uv

The official standalone installer works on armv7l:

```bash
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:

```bash
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](https://docs.astral.sh/uv/reference/policies/platforms/) 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](https://github.com/astral-sh/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](https://github.com/astral-sh/uv/issues/6873), [astral-sh/uv#17210](https://github.com/astral-sh/uv/issues/17210)). If `uv python install` errors out with a libc-related message, point uv at the system Python instead:

```bash
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](https://www.piwheels.org/) 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`:

```toml {filename="~/.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](https://www.piwheels.org/faq.html) 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](https://github.com/astral-sh/uv/issues/9866) tracks the bug.

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

```bash
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](https://pydevtools.com/handbook/how-to/how-to-run-python-scripts-on-a-raspberry-pi-with-uv.md) covers the standard 64-bit Pi OS path.
- [How to install uv on Linux](https://pydevtools.com/handbook/how-to/how-to-install-uv-on-linux.md) covers shell completions and PATH troubleshooting that apply on Pi OS too.
- [piwheels project](https://www.piwheels.org/) hosts precompiled armv7l wheels for 32-bit Pi OS.
- [uv platform support policy](https://docs.astral.sh/uv/reference/policies/platforms/) lists every architecture uv targets and the support tier for each.
- [astral-sh/uv#9866](https://github.com/astral-sh/uv/issues/9866) tracks the 32-bit userland on 64-bit kernel bug.