Install & Compatibility
Where this runs
tested against v4.1.1 · 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
muslpy 3.10–3.960 runs
installs and imports cleanly · install 0.0s · import 0.701s · 51.6MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 5.4s · import 0.680s · 53MB
56MB installed
● package 56MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cache
✓ from oslo_cache import core as cache
ConfigurationError
✓ from oslo_cache.exception import ConfigurationError
create_region
✓ from oslo_cache.core import create_region
get_memoization_decorator
✓ from oslo_cache.core import get_memoization_decorator
This quickstart demonstrates how to set up and use `oslo.cache` with `oslo.config` for memoization. It initializes a cache region and applies a memoization decorator to a function. The first call to `get_heavy_computation_result` will execute the function, subsequent calls with the same arguments will retrieve the cached value. This example uses the `dogpile.cache.memory` backend, suitable for in-process caching. For production, backends like Memcached or Redis are recommended.
import os
from oslo_config import cfg
from oslo_cache import core as cache
CONF = cfg.CONF
def register_cache_opts():
cache_group = cfg.OptGroup('cache', title='Cache Options')
CONF.register_group(cache_group)
cache.register_opts(CONF)
# Simulate loading configuration (e.g., from a config file)
# In a real OpenStack project, this would be handled by oslo.config setup
# For a simple script, we can set some options directly
CONF.set_default('backend', 'dogpile.cache.memory', group='cache')
CONF.set_default('expiration_time', 3600, group='cache')
register_cache_opts()
cache.configure(CONF)
example_cache_region = cache.create_region(name='my_app_cache')
MEMOIZE = cache.get_memoization_decorator(
CONF, example_cache_region, 'cache'
)
@MEMOIZE()
def get_heavy_computation_result(value):
print(f"Performing heavy computation for: {value}")
return value * 2
if __name__ == '__main__':
print(get_heavy_computation_result(10))
print(get_heavy_computation_result(10)) # This should be cached
print(get_heavy_computation_result(20))
print(get_heavy_computation_result(20)) # This should be cached
Debug
Known issues
breakingThe MongoDB backend support was removed in `oslo.cache` version 4.0.0. Projects upgrading from older versions that relied on `dogpile.cache.mongo` will encounter `ConfigurationError` or import issues. This was done to align with Semantic Versioning due to a long-standing broken state with `pymongo` versions 3.x and later.fixMigrate to a supported backend like Memcached or Redis. If still on older `oslo.cache` and `pymongo` versions, ensure `pymongo<3.0` is used, though this is highly discouraged due to security and compatibility issues.
affects: >=4.0.0
deprecatedThe `[cache]` section options `memcache_username` and `memcache_password` are deprecated and will be removed in a future release, leading to deprecation warnings. These were used for SASL authentication with Memcached.fixUse the `backend_argument` option to pass Memcached client-specific authentication details, or use environment variables where appropriate for the chosen Memcached client library.
affects: All versions (deprecation warnings present)
gotchaIncorrect configuration order can lead to `oslo.cache` not functioning as expected or raising `ConfigurationError`. Specifically, `cache.configure()` must be called before `cache.create_region()`, and `create_region()` must be called before `get_memoization_decorator()` or `configure_cache_region()` are used. The config file should be fully loaded before `configure_cache_region()` is invoked, and all setup calls must complete before a decorated function is used.fixAlways follow the recommended configuration order: register options, load config, `cache.configure(CONF)`, `cache.create_region()`, then `cache.get_memoization_decorator()` or `cache.configure_cache_region()`.
affects: All versions
Errors
Common errors & fixes
oslo_cache.exception.ConfigurationError: Unsupported cache backend: dogpile.cache.mongo
Attempting to use the `dogpile.cache.mongo` backend with `oslo.cache` version 4.0.0 or newer. This backend was explicitly removed.
fixUpdate your configuration to use a supported backend such as `dogpile.cache.memcached`, `oslo_cache.memcache_pool`, or `dogpile.cache.redis`. Ensure the necessary backend dependencies are installed (e.g., `pip install python-memcached` or `pip install redis`).
DeprecationWarning: The oslo namespace package is deprecated. Please use oslo_config instead.
This warning typically indicates an older `oslo.config` import pattern (e.g., `from oslo.config import cfg`) being used in a project that depends on `oslo.cache`. While not directly from `oslo.cache`, it's a common OpenStack-related dependency warning.
fixEnsure all `oslo` libraries are updated to their latest compatible versions. Specifically, update `oslo.config` and any code importing it to use `from oslo_config import cfg`.
oslo_cache.exception.ConfigurationError: No cache backend specified. Please set 'backend' option under the '[cache]' section in your configuration.
The `backend` option for the cache region has not been set in the configuration, which is mandatory for `oslo.cache` to know which `dogpile.cache` backend to utilize.
fixAdd `backend = dogpile.cache.<your_chosen_backend>` to the `[cache]` section of your configuration file or set it programmatically using `CONF.set_default('backend', 'dogpile.cache.<your_chosen_backend>', group='cache')`. Replace `<your_chosen_backend>` with a suitable option like `memory`, `memcached`, `redis`, etc. Upgrade
Version history
4.2.0latest on PyPI · released May 20, 2026
Audit
Dependencies
dogpile.cacherequiredCore caching backend wrapper.
oslo.configrequiredUsed for configuration options.
oslo.i18nrequiredInternationalization utilities.
oslo.logrequiredLogging configuration library.
oslo.utilsrequiredCommon utilities.