pylibmc install fails from tests requirements on Python 3.12+ without libmemcached installed

[Kiko Barr]

😀 Hello from the Django sprint at PyCon 2026!

High Level Overview

When following the Unit Tests walkthrough, python -m pip install -r tests/requirements/py3.txt is failing to install pylibmc. This is because Django pyproject.toml requires CPython 3.12+, but wheel for pylimbc hosted on PyPI only goes up to 3.11. See PyPI: ​https://pypi.org/project/pylibmc/#files

Six people at the sprint encountered this same issue. I think this is important to document because new contributors are encouraged to start by running tests and then they run into this issue. While many of the tests can still be run, some will produce errors if pylibmc is not pre-installed.

There have been several previous Django-related posts discuss removing pylibmc as a dependency, but have not come to a conclusion. While the discussion is occurring, I think it would be good to update the test documentation with some short-term workarounds in the meantime.

Django closed issues:

• https://code.djangoproject.com/ticket/36427
• https://code.djangoproject.com/ticket/36153

Django forum posts:

• ​https://forum.djangoproject.com/t/error-when-installing-requirements-for-django-tests-fatal-error-libmemcached-memcached-h-file-not-found-include-libmemcached-memcached-h/1685
• ​https://forum.djangoproject.com/t/should-we-stop-recommending-pylibmc/42993

pylibmc issue:

• ​https://github.com/lericson/pylibmc/issues/288

Reproducing the Issue

The issue appears while running commands from the "Quickstart" instruction in the "Unit Tests" documentation, found here: ​https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/unit-tests/#quickstart

Based on the documentation, I created a virtual environment and ran these commands:

git clone https://github.com/YourGitHubName/django.git django-repo  
# created and activated the venv here and ran the rest of the commands  
cd django-repo/tests  
python -m pip install -e ..  

However, the next command will fail:

python -m pip install -r requirements/py3.txt  

This is the error message:

Building wheels for collected packages: pylibmc  
  Building wheel for pylibmc (pyproject.toml) ... error  
  error: subprocess-exited-with-error  
    
  × Building wheel for pylibmc (pyproject.toml) did not run successfully.  
  │ exit code: 1  
  ╰─> [6 lines of output]  
      In file included from src/_pylibmcmodule.c:34:  
      src/_pylibmcmodule.h:42:10: fatal error: 'libmemcached/memcached.h' file not found  
         42 | #include <libmemcached/memcached.h>  
            |          ^~~~~~~~~~~~~~~~~~~~~~~~~  
      1 error generated.  
      error: command '/usr/bin/clang' failed with exit code 1  
      [end of output]  
    
  note: This error originates from a subprocess, and is likely not a problem with pip.  
  ERROR: Failed building wheel for pylibmc  
Failed to build pylibmc  
error: failed-wheel-build-for-install

× Failed to build installable wheels for some pyproject.toml based projects  
╰─> pylibmc  

Issue Description

Issue for those running Python 3.12 with no libmemcached installed:

• When running python -m pip install -r requirements/py3.txt, pip reads requirements/py3.txt and sees pylibmc.
• pip queries PyPI for pylibmc distributions, including wheel files (.whl) and source archive (.tar.gz / .zip, called sdist)
• Since there is no wheel for Python 3.12, pip does not use the wheel install and instead downloads the sdist to build pylibmc locally.
• The source build compiles C code for pylibmc, which needs libmemcached headers/libraries. If libmemcached is not installed, then this step fails, producing the error from above, src/_pylibmcmodule.h:42:10: fatal error: 'libmemcached/memcached.h' file not found

Additional issue for some on macOS:

• Even after libmemcached was installed globally, people on macOS continued to run on the same error. This is because Homebrew, a very common package manager for macOS, often installs under a non-default prefix (usually /opt/homebrew). If that prefix isn’t in the compiler/linker search paths for that shell/build, compile fails even though libmemcached is installed.
• People on macOS had to run additional commands to direct clang to the right path using CPPFLAGS to tell compiler where headers are and LDFLAGS to tell linker where libs are.

Short-term Workaround

Of the six people at the sprint who encountered this same issue, there were several different versions of the same workaround.

For four of us on Macs, we needed to first install libmemcached headers (someone else also had to install memcached, zlib, and pkg-config to get it to work, which may be worth looking into):

# install globally outside of venv  
brew install libmemcached

# run these inside of the venv  
export CPPFLAGS="-I$(brew --prefix)/include"  
export LDFLAGS="-L$(brew --prefix)/lib"  
python -m pip install -r requirements/py3.txt  

Someone on Linux Omarchy only had to run:

sudo pacman -S libmemcached-awesome

Someone else on Linux Debian ran:

sudo apt install libmemcached-dev

Listing all these variations for different operating systems is not the most elegant solution, but it does facilitate a smoother onboarding experience for new contributors.

[Sarah Boyce]

Agree we should either document or try to improve the install experience

[Malte Gerth]

The same issue was discussed and the PyCon Italy 2026 again.

There are already multiple issues and some discussion around this issue.

• https://code.djangoproject.com/ticket/27876
• https://code.djangoproject.com/ticket/29405
• ​https://forum.djangoproject.com/t/error-when-installing-requirements-for-django-tests-fatal-error-libmemcached-memcached-h-file-not-found-include-libmemcached-memcached-h/1685

Maybe the already existing MR could be reused and be accepted?

• ​https://github.com/django/django/pull/12660

There is already a conditional exclude for pylibmc in the test requirements for windows. Maybe add MacOS as-well?

# pylibmc/libmemcached can't be built on Windows.
pylibmc; sys_platform != 'win32'

[Tim Schilling]

Would an admonition that includes the error message and then links to a Django wiki page that has various platform solutions be amenable? That allows searching the docs to find the solution, but avoids flooding our docs with the various platforms' solutions.

I'm not sure the upstream problem will be solved soon. The project is hopefully transitioning maintainers, but it's in limbo: ​https://github.com/lericson/pylibmc/issues/297

[Tim Schilling]

The python-memcached library is also in a similar state of not being updated in 8 months with the last release in 2024: ​https://github.com/linsomniac/python-memcached

[Tim Graham]

I think the simplest option would be to instruct contributors to comment out the dependency if it doesn't install for them as they're unlikely to need it.

[Johannes Maron]

Ref #37098

We just added support to pass LIBMEMCACHED to tox.

The following works on a fresh macOS with Homebrew:

brew install libmemcached
echo 'export LIBMEMCACHED="${HOMEBREW_PREFIX}"' >> ~/.profile

[Johannes Maron]

BTW, if we update the docs, maybe we point people towards Tox instead of manually fiddling with ./tests/runtests.py

tox -e py3 -- path.to.test
# and
tox -e docs

works for OK most patches unless you have to run Selenium or, worse, Oracle…

[Tim Schilling]

The person who had offered to help maintain pylibmc has started maintaining a fork until activity resumes: ​https://pypi.org/project/pylibmc2/

[Jacob Walls]

Replying to Tim Schilling:

The person who had offered to help maintain pylibmc has started maintaining a fork until activity resumes: ​https://pypi.org/project/pylibmc2/

Let's keep the discussion about what to do about pylibmc in general to the ​forum thread, but I take the point that with over a dozen people finding it a nontrivial research project to figure out how to install it, it's not a good sign.

---

Tim G's suggestion in comment:6 is a good compromise given our general stance against vendoring install instructions for packages (#29405). Contributors are unlikely to need the cache libraries, as the tests are skipped anyway unless you add pylibmc in your settings file, and most sprint contributors are using test_sqlite.py, which does not configure any caches.

Kiko, are you up for a tiny docs tweak to suggest commenting out requirements pertaining only to tests that do not run under the default test_sqlite.py configuration, or something like that?

Or even supplementing the advice to search the web with "or the Django forum"? (Here is the ​solution that ought to be marked as the "solution" IMO.) Sounds obvious, but since this was not a Django issue, my first search did not include "Django Forum", so I found mostly garbage. (Apparently I still Google like it's 2015...)

[Kiko Barr]

Definitely! I can make a PR for the tiny docs tweak this weekend. I will try to link it here by Sunday night.

[Tim Schilling]

Kiko, are you up for a tiny docs tweak to suggest commenting out requirements pertaining only to tests that do not run under the default test_sqlite.py configuration, or something like that?

Shouldn't we comment it out in the requirements file to start and leave it to the folks who need it to figure out what to install instead? I'm not sure we should plan on this resolving soon.

[Tim Graham]

Replying to Tim Schilling:

Shouldn't we comment it out in the requirements file to start and leave it to the folks who need it to figure out what to install instead? I'm not sure we should plan on this resolving soon.

CI uses that file to install dependencies, so that approach would create some complication.

[Tim Schilling]

Replying to Tim Graham:

CI uses that file to install dependencies, so that approach would create some complication.

Good point. Would this be a case to introduce a requirements-ci.txt file? If not, a docs change to account for it seems reasonable.