Install & Compatibility
Where this runs
tested against v1.6.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 1.53s
py 3.11
✕ build_error
✓ 1.6s
py 3.12
✕ build_error
✕ build_error
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 1.8s
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from pylibmc import Client
ThreadMappedPool
✓ from pylibmc import ThreadMappedPool
This quickstart demonstrates how to connect to a memcached server using `pylibmc.Client`, perform basic `set`, `get`, and `delete` operations, and handle optional SASL authentication using environment variables. It highlights setting expiry times and utilizing the binary protocol.
import pylibmc
import os
# Memcached server addresses, can be an environment variable (e.g., for MemCachier).
# For local testing, use ['127.0.0.1:11211']. Multiple servers can be listed.
servers = os.environ.get('MEMCACHIER_SERVERS', '127.0.0.1:11211').split(',')
username = os.environ.get('MEMCACHIER_USERNAME', '')
password = os.environ.get('MEMCACHIER_PASSWORD', '')
# Initialize client. 'binary=True' enables the binary protocol, 'tcp_nodelay' improves performance.
# SASL authentication is used if username and password are provided.
if username and password:
mc = pylibmc.Client(servers, binary=True, behaviors={"tcp_nodelay": True}, username=username, password=password)
else:
mc = pylibmc.Client(servers, binary=True, behaviors={"tcp_nodelay": True})
# Basic operations
key = "my_test_key"
value = "Hello from pylibmc!"
# Set a value with an expiry of 60 seconds
success_set = mc.set(key, value, time=60)
print(f"Set '{key}' to '{value}': {success_set}")
# Get the value
retrieved_value = mc.get(key)
print(f"Retrieved '{key}': {retrieved_value}")
# Set multiple values
mc.set_multi({"key1": "value1", "key2": 123})
print(f"Retrieved 'key1': {mc.get('key1')}")
# Delete a key
success_delete = mc.delete(key)
print(f"Deleted '{key}': {success_delete}")
print(f"'{key}' after deletion: {mc.get(key)}")
Debug
Known issues
breakingVersion 1.6.0 introduced partial incompatibility with older versions, specifically affecting interoperability with `python-memcached` due to a flag conflict. Unicode strings are now stored as UTF-8 instead of being pickled by default.fixFor interoperability with older clients or Python 2/3, explicitly set the `pickle_protocol` behavior (e.g., `mc.behaviors['pickle_protocol'] = 2`).
affects: 1.6.0+
gotchapylibmc is a C extension and requires the `libmemcached` C library (including development headers) to be installed on your system before `pip install pylibmc`. Without it, installation will fail with compilation errors like 'libmemcached/memcached.h: No such file or directory'.fixInstall `libmemcached-dev` (Debian/Ubuntu), `libmemcached-devel` (RHEL/CentOS), or `libmemcached` (Homebrew on macOS) using your system's package manager. For example: `sudo apt-get install libmemcached-dev python3-dev`.
affects: All versions
gotchaFor SASL authentication, typically required by cloud memcached providers, the system-level `libsasl2-modules` (or equivalent) must be installed. Failure to do so will result in 'FAILED TO SEND AUTHENTICATION TO SERVER' errors.fixInstall `libsasl2-modules` (Debian/Ubuntu) or equivalent on your operating system.
affects: All versions
gotchaIn multithreaded environments, a single `pylibmc.Client` object is not thread-safe and can lead to issues. For safe and performant concurrent access, pooling mechanisms are necessary.fixUse `pylibmc.ThreadMappedPool` or other pooling helpers provided by the library to manage client instances per thread.
affects: All versions
gotchaThe `behaviors` configuration for `pylibmc.Client` can be set either via the constructor's `behaviors` keyword argument (newer versions) or by modifying the `mc.behaviors` attribute after instantiation (older versions). Mixing or using only the attribute in older versions could lead to unexpected behavior.fixFor robust compatibility, especially if supporting older `pylibmc` versions, set behaviors using `mc.behaviors = {...}` after client creation, or ensure you are passing `behaviors` as a keyword argument if on a modern `pylibmc` version. affects: Older versions (<1.0) primarily, but good practice for compatibility.
gotchaThere are reports of an exception being swallowed on startup under Python 3.13 that has a fix in the GitHub repository but has not been included in a release since 2022. This suggests potential compatibility issues with Python 3.13 and newer.fixIf encountering issues on Python 3.13+, consider checking the latest development branch for fixes or using a slightly older Python version until a new `pylibmc` release.
affects: Potentially 3.13+
Upgrade
Version history
1.6.3latest on PyPI · released Aug 30, 2022
Audit
Dependencies
libmemcachedrequiredCore C library that pylibmc wraps; must be installed system-wide with development headers.
python-dev / python3-devrequiredRequired on Linux systems for building Python C extensions.
libsasl2-modulesoptionalRequired for SASL authentication support with memcached servers.
zliboptionalOptionally used for data compression.