If you’re running Arch Linux and trying to build Anki from source, you may have encountered a frustrating build failure related to Python 3.14. Here’s what went wrong and how I fixed it.

The Problem

Arch Linux recently updated to Python 3.14.2 as the system default. When attempting to build Anki from the main branch, the build failed with this error:

error: the configured Python interpreter version (3.14) is newer than PyO3's maximum supported version (3.13)
= help: please check if an updated version of PyO3 is available. Current version: 0.23.3

The issue is that Anki depends on orjson, a fast JSON library written in Rust. This library uses PyO3 for Python bindings, and the bundled version (0.23.3) only supports Python up to 3.13.

Why UV_PYTHON and .python-version Didn’t Work

My first attempts involved setting the UV_PYTHON environment variable and creating a .python-version file in the repository root. Neither worked because Anki’s build runner wasn’t passing these settings through to uv when creating the virtual environment. The build system kept detecting and using /usr/bin/python3 (3.14.2) regardless.

The Solution

The fix is to install Python 3.13 via pyenv and put it first in your PATH so it gets detected before the system Python.

First, install pyenv and Python 3.13:

sudo pacman -S pyenv
pyenv install 3.13.1

Then, for your build session, prepend Python 3.13 to your PATH:

export PATH="$HOME/.pyenv/versions/3.13.1/bin:$PATH"

Now clean the build directory and rebuild:

cd ~/ankidev/anki
rm -rf out
./tools/runopt

The build should now complete successfully, with the virtual environment using Python 3.13.1:

./out/pyenv/bin/python --version
Python 3.13.1

Making It Permanent

If you regularly build Anki, add the PATH modification to your shell configuration:

echo 'export PATH="$HOME/.pyenv/versions/3.13.1/bin:$PATH"' >> ~/.bashrc

Alternatively, create a simple wrapper script for building Anki that sets the PATH temporarily.

Conclusion

This is a temporary issue that will resolve itself once orjson updates its bundled PyO3 to a version that supports Python 3.14. Until then, using pyenv to provide Python 3.13 is a clean workaround that doesn’t require downgrading your system Python or breaking other applications.

The Arch Linux philosophy of staying on the bleeding edge occasionally runs into these compatibility gaps with projects that have Rust dependencies—something to keep in mind when building from source.