MoleculerPy is a fast, modern and powerful microservices framework for Python. It helps you to build efficient, reliable & scalable services. MoleculerPy provides many features for building and managing your microservices.
Website: https://moleculerpy.services
Documentation: https://moleculerpy.services/docs
- Async/await native (built on asyncio)
- Request-reply concept
- Support event driven architecture with balancing
- Built-in service registry & dynamic service discovery
- Load balanced requests & events (round-robin, random, cpu-usage, latency, sharding)
- Many fault tolerance features (Circuit Breaker, Bulkhead, Retry, Timeout, Fallback)
- Plugin/middleware system (19 built-in middlewares)
- Support Streams for large data transfer
- Service mixins
- Built-in caching solution (Memory, Redis)
- Pluggable loggers (structlog)
- Pluggable transporters (NATS, Redis, Memory)
- Pluggable parameter validator
- Multiple services on a node/server
- Master-less architecture, all nodes are equal
- Built-in metrics feature with Prometheus exporter
- Built-in tracing feature with Console exporter
- Official REPL and Channels modules
pip install moleculerpyWith optional features:
# With Redis transporter
pip install moleculerpy[redis]
# With metrics & tracing
pip install moleculerpy[metrics,tracing]
# All features
pip install moleculerpy[all]This example shows you how to create a small service with an add action which can add two numbers and how to call it.
import asyncio
from moleculerpy import ServiceBroker, Service, action, Context
# Define a service
class MathService(Service):
name = "math"
@action
async def add(self, ctx: Context):
return ctx.params["a"] + ctx.params["b"]
async def main():
# Create a broker
broker = ServiceBroker()
# Register the service
await broker.register(MathService())
# Start the broker
await broker.start()
# Call service
result = await broker.call("math.add", {"a": 5, "b": 3})
print(f"5 + 3 = {result}")
# Stop broker
await broker.stop()
asyncio.run(main())MoleculerPy includes a CLI that allows you to easily start a broker and load services:
moleculerpy <service_directory> [options]| Option | Description | Default |
|---|---|---|
service_directory |
Path to directory containing service files | - |
--broker-id, -b |
Broker ID | node-<current_dir_name> |
--transporter, -t |
Transporter URL | nats://localhost:4222 |
--log-level, -l |
Log level | INFO |
--log-format, -f |
Log format (PLAIN, JSON) | PLAIN |
--namespace, -n |
Service namespace | default |
# Start with services from the 'services' directory
moleculerpy services
# Custom broker ID and transporter
moleculerpy services -b my-broker -t nats://nats-server:4222
# Verbose logging
moleculerpy services -l DEBUGWe have official modules for MoleculerPy:
| Module | Description |
|---|---|
| moleculerpy-repl | Interactive CLI shell for debugging and managing services |
| moleculerpy-channels | Reliable pub/sub messaging with Redis, Kafka, NATS |
MoleculerPy provides a powerful middleware system to extend functionality. Middlewares can hook into various stages of request, event, and lifecycle processes.
from moleculerpy.middleware import Middleware
from moleculerpy.context import Context
class LoggingMiddleware(Middleware):
async def local_action(self, next_handler, action_endpoint):
async def wrapped_handler(ctx: Context):
print(f"Before action: {action_endpoint.name}")
result = await next_handler(ctx)
print(f"After action: {action_endpoint.name}")
return result
return wrapped_handler
# Register middleware
broker = ServiceBroker(middlewares=[LoggingMiddleware()])local_action(next_handler, action_endpoint)- Wraps local action handlersremote_action(next_handler, action_endpoint)- Wraps remote action callslocal_event(next_handler, event_endpoint)- Wraps local event handlers
broker_created(broker)- Called after broker initializationbroker_started(broker)- Called after broker startupbroker_stopped(broker)- Called after broker shutdownservice_created(service)- Called after service registrationservice_started(service)- Called after service startup
- Core framework with full service lifecycle
- 7 Transporters: NATS, Redis/Valkey, Memory, MQTT, AMQP, Kafka, TCP+Gossip (P2P)
- 4 Serializers: JSON, MsgPack, CBOR (-29% vs JSON), ProtoBuf (-25% vs JSON)
- TCP Transporter — peer-to-peer without external broker, Gossip protocol for discovery
- Service versioning —
v1.users.get,v2.users.getcoexistence,$noVersionPrefix - Pluggable serializers (JSON, MsgPack) — MsgPack 2x faster on large payloads
- Balanced request/event handling via NATS queue groups (
disable_balancer=True) - 4/4 transit middleware hooks (publish, send, receive, message handler)
- 22 built-in middlewares
- 6 load balancing strategies (including Shard)
- Circuit breaker, bulkhead, retry patterns
- Pluggable metrics (Console, Prometheus) & tracing (Console, Event, Jaeger, Zipkin)
- Pluggable validators (BaseValidator + DefaultValidator)
- LRU memory cacher with eviction
- $node service (7 actions), broker.mcall(), ping, health check
- Streaming support
- Protocol v4 safety: version check, NodeID conflict detection
- REPL (18 commands) & Channels (Redis, NATS) modules
- API Gateway (moleculerpy-web v0.1.0)
- TCP transporter TLS/shared_secret security
- CBOR + ProtoBuf serializers
- Database adapters (moleculerpy-db)
- GraphQL gateway
- gRPC support
You can find the documentation at https://moleculerpy.services/docs.
See CHANGELOG.md.
We welcome you to join in the development of MoleculerPy. Please read our contribution guide.
This project is based on pylecular by Alvaro Inckot, licensed under MIT License.
Inspired by Moleculer.js - the original Node.js microservices framework.
MoleculerPy is available under the MIT license.
Copyright (c) 2026 MoleculerPy
