{"id":2700,"library":"pymemcache","title":"pymemcache","description":"pymemcache is a comprehensive, fast, pure-Python client for memcached. It fully implements the memcached text protocol and supports connections over UNIX sockets, TCP (IPv4 or IPv6), and configurable timeouts. It is currently at version 4.0.0 and maintains an active release cadence.","status":"active","version":"4.0.0","language":"en","source_language":"en","source_url":"https://github.com/pinterest/pymemcache","tags":["memcached","caching","client","pure-python"],"install":[{"cmd":"pip install pymemcache","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires a running memcached server to function.","package":"memcached","optional":false}],"imports":[{"note":"Common mistake when migrating from the older 'python-memcached' library.","wrong":"from memcache import Client","symbol":"Client","correct":"from pymemcache.client.base import Client"},{"note":"While 'HashClient' can be imported directly from 'pymemcache' since v3.3.0, the explicit path 'pymemcache.client.hash' is also widely used and clear.","wrong":"from pymemcache import HashClient (prior to v3.3.0)","symbol":"HashClient","correct":"from pymemcache.client.hash import HashClient"}],"quickstart":{"code":"import os\nfrom pymemcache.client.base import Client\n\nMEMCACHED_HOST = os.environ.get('MEMCACHED_HOST', '127.0.0.1')\nMEMCACHED_PORT = int(os.environ.get('MEMCACHED_PORT', '11211'))\n\n# It's highly recommended to set timeouts to prevent blocking indefinitely\nclient = Client((MEMCACHED_HOST, MEMCACHED_PORT), connect_timeout=1, timeout=0.5)\n\nkey = 'my_test_key'\nvalue = 'my_test_value'\n\n# Set a key-value pair\nsuccess = client.set(key, value, expire=60) # expire in 60 seconds\nprint(f\"Set '{key}': {value} - Success: {success}\")\n\n# Get the value back\nretrieved_value = client.get(key)\nif retrieved_value:\n    # pymemcache returns bytes, decode to string if necessary\n    print(f\"Retrieved '{key}': {retrieved_value.decode('utf-8')}\")\nelse:\n    print(f\"Key '{key}' not found or expired.\")\n\nclient.close()","lang":"python","description":"This quickstart demonstrates how to connect to a memcached server using `pymemcache.Client`, set a key-value pair with an expiration, and retrieve it. Note that `pymemcache` returns values as bytes, requiring explicit decoding for string values."},"warnings":[{"fix":"Upgrade to Python 3.7+ or pin pymemcache to <4.0.0.","message":"Version 4.0.0 dropped official support for Python 2.7, 3.4, and 3.5. Ensure your project uses Python 3.7 or newer before upgrading to v4.0.0.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"After retrieval, use `.decode('utf-8')` (or appropriate encoding) on the returned value: `value.decode('utf-8')`.","message":"`get()` and `get_many()` methods return values as `bytes`, not `str`. You must explicitly decode the retrieved bytes if you expect a string.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure keys are ASCII compliant. For unicode keys, instantiate the client with `allow_unicode_keys=True` and ensure consistent encoding (e.g., UTF-8) across clients.","message":"Memcached keys must adhere to the ASCII protocol and cannot contain spaces, newlines, carriage returns, or null characters by default. Using non-ASCII or illegal characters will raise `MemcacheIllegalInputError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Convert any float `expire` values to `int`.","message":"The `expire` argument (previously `time` in `python-memcached`) for set operations now strictly expects an integer representing seconds. Floating-point values are no longer accepted.","severity":"breaking","affected_versions":"All versions"},{"fix":"Update custom serialization logic to use the `serde` object pattern. For example: `client = Client(..., serde=MyCustomSerde())`.","message":"In version 3.0.0, the serialization API was refactored. Instead of separate `serializer` and `deserializer` arguments, client objects now expect a single `serde` object that implements `serialize` and `deserialize` methods.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always provide explicit `connect_timeout` and `timeout` values (e.g., `Client(..., connect_timeout=1, timeout=0.5)`).","message":"Failing to set `connect_timeout` and `timeout` in client constructors can cause your application to block indefinitely if the memcached server is slow or unavailable. This is crucial for production environments.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}