How to fix pygame-ce upgrade/build errors on Debian: install libportmidi-dev to resolve Meson portmidi dependency

Upgrading pygame-ce on Debian fails with a Meson 'portmidi' not found error. Install libportmidi-dev and rerun pip install --upgrade pygame-ce to finish.

Upgrading pygame-ce on a Debian-based system can fail with a Meson build error about a missing library. The output points to portmidi not being available during the build, which prevents the wheel from being prepared and stops the installation.

Reproducing the failure

The typical upgrade command looks like this, and it can break with a metadata-generation error:

pip install --upgrade pygame-ce

The relevant part of the log makes the root cause explicit:

Run-time dependency portmidi found: NO (tried pkgconfig and cmake)
../meson.build:302:25: ERROR: C shared or static library 'portmidi' not found

In the same output you may notice details like Python 3.9 being used, Meson running as the backend, and other dependencies being detected correctly (SDL2, SDL2_image, SDL2_mixer, SDL2_ttf, freetype). The only failing dependency here is portmidi.

What’s going on under the hood

pygame-ce is built with Meson, which resolves system libraries via pkg-config and CMake. On Debian-family distributions, development headers are packaged separately. If a build step needs a C library at compile time, the “-dev” package must be present. The log says portmidi was not found, which means the development package is missing on the host where pip is trying to build pygame-ce.

Fix and verified commands

On Debian-based systems, install the correct development package and retry the upgrade. The package name to pull in is libportmidi-dev.

sudo apt install libportmidi-dev

After installing it, run the upgrade again:

pip install --upgrade pygame-ce

If you are working inside a virtual environment, make sure the development packages are installed on the system that provides headers for the Python version you are using in that environment.

When you are unsure about package names, search the repo before installing. On Debian-family systems this helps surface the exact name:

apt search portmidi

Why this matters

Build backends like Meson will attempt to compile native extensions and link them against system libraries. If a required library or its headers are missing, the build fails even though pip itself is working as expected. Understanding the signal in the log—especially lines like “Run-time dependency portmidi found: NO” and the final “C shared or static library 'portmidi' not found”—lets you fix the environment quickly instead of chasing pip or version issues.

Conclusion

When pygame-ce fails to build on a Debian or Raspbian system with a portmidi error, the solution is to install libportmidi-dev and rerun the upgrade. Read the Meson output carefully to identify the exact missing dependency, search the package repository if needed, and keep your development packages aligned with the Python toolchain you’re using. This small bit of environment hygiene saves a lot of time on native-build Python packages.