Install & Compatibility
Where this runs
tested against v4.6.0 · 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.920 runs
installs and imports cleanly · install 0.0s · import 1.293s · 60.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.5s · import 1.228s · 58MB
63MB installed
● package 63MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
service
✓ from oslo_service import service
Primary module for service base classes and launcher functions.
cfg
✓ from oslo_config import cfg
Commonly used alongside oslo.service for configuration, often aliased as 'cfg'.
This quickstart demonstrates how to define a basic service using `oslo_service.service.ServiceBase` and launch it with `oslo_service.service.launch`. It includes integration with `oslo_config` for defining and reading configuration options, such as the number of worker processes. The `start`, `stop`, and `wait` methods illustrate the service lifecycle.
import os
from oslo_config import cfg
from oslo_service import service
# Define a simple configuration option
service_opts = [
cfg.IntOpt('workers', default=1, min=1, help='Number of worker processes')
]
CONF = cfg.CONF
CONF.register_opts(service_opts, group='my_service')
class MyService(service.ServiceBase):
def __init__(self, conf):
super().__init__(conf)
self.conf = conf
self.should_stop = False
print(f"Service initialized with {self.conf.my_service.workers} workers.")
def start(self):
print(f"Service worker {os.getpid()} starting...")
# Simulate some work
# In a real service, this would be a long-running loop or event listener
def stop(self):
self.should_stop = True
print(f"Service worker {os.getpid()} stopping...")
def wait(self):
# In a real service, this would block until stop() is called
import time
while not self.should_stop:
time.sleep(0.1)
def main():
CONF(args=[], project='my_app') # Pass empty args to avoid argparse errors if not parsing CLI
# Instantiate your service
my_service_instance = MyService(CONF)
# Launch the service with workers
# Note: oslo.service's launch function creates a Launcher internally
# and manages worker processes if `workers` > 1.
# For a simple example, we often directly call the Service's methods.
# For multi-process, `service.launch` is key.
launcher = service.launch(CONF, my_service_instance, workers=CONF.my_service.workers)
print(f"Launcher started for PID {os.getpid()} with {CONF.my_service.workers} workers.")
# Wait for the service to complete (e.g., via signal handler or internal logic)
launcher.wait()
print("All services stopped.")
if __name__ == '__main__':
# To run this, you might need to install oslo.config and oslo.service
# and ideally run with python -m your_script_name
# This example demonstrates the basic structure, but running actual
# multi-worker services requires more robust signal handling and process management
# which oslo.service provides internally.
main()
Debug
Known issues
breakingFuture versions of oslo.service are removing the Eventlet dependency, which will significantly impact services heavily relying on Eventlet's green thread model for concurrency (e.g., `loopingcall`, `periodic task`, `wsgi`, `threadgroup`). This is a mandatory architectural shift within OpenStack.fixReview OpenStack's 'remove-eventlet-from-oslo-service' specification for migration strategies and alternative concurrency models. Services might need to re-architect parts of their concurrent operations.
affects: Versions after 4.x (exact target version for full removal is in flux, but migration is ongoing).
gotchaEncountering 'oslo_config.cfg.DuplicateOptError' when defining configuration options, especially in complex OpenStack deployments or when integrating multiple oslo libraries.fixEnsure that configuration options are registered only once. This can often occur due to improper import ordering or multiple components attempting to register the same option. Refactor imports or use `cfg.CONF.register_opts(..., enforce_type=False)` (use with caution) or check `cfg.CONF.list_opts()` before registering.
affects: All versions using oslo.config.
gotchaServices using `oslo.messaging` may encounter `OSError: Server unexpectedly closed connection` or `oslo_messaging.exceptions.MessageUndeliverable` errors, often related to RabbitMQ issues or network instability.fixVerify RabbitMQ service status and connectivity. Check RabbitMQ logs for 'missed heartbeats' or 'queue not found' errors. Ensure correct `transport_url` configuration in `oslo.config` and proper RabbitMQ user permissions and policies. Increase heartbeat timeouts if network latency is a factor.
affects: All versions using oslo.messaging for RPC.
Errors
Common errors & fixes
OSError: Server unexpectedly closed connection
Often indicates a dropped connection to the message broker (e.g., RabbitMQ) due to network issues, broker overload, or missed heartbeats.
fixCheck network connectivity between the service and RabbitMQ. Review RabbitMQ logs for errors like 'missed heartbeats from client'. Consider increasing `rabbit_heartbeat_timeout_threshold` in `oslo.config` to tolerate brief network hiccups.
oslo_messaging.exceptions.MessageUndeliverable
A message could not be delivered to its intended recipient, typically because the target queue does not exist or the connection was lost before delivery.
fixEnsure the receiving service is running and its message queues are properly initialized. Verify that the routing keys and topics configured for message publication match the expected queue bindings on the consumer side. Check RabbitMQ management interface for queue existence.
Upgrade
Version history
4.6.0latest on PyPI · released May 18, 2026
Audit
Dependencies
oslo.configrequiredFundamental for configuration management within Oslo projects.
oslo.utilsrequiredProvides common utility functions like encoding, exception handling, and time management.
oslo.contextrequiredHelpers to maintain useful information about a request context, often populated in WSGI pipelines.
eventletoptionalHistorically a core dependency for concurrency (green threads), but is being phased out in future versions (see warnings).