---
id: spark
version: "0.4.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# Spark — An easy to use actor model framework in Python

License: permissive · Maintenance: active · Downloads: 80.5K/mo

## What it is and what it does

Spark is an async actor framework that abstracts concurrent work into independent actors that communicate by message passing. You define actors by subclassing `Actor` and implementing `process()`, then create and manage them through a `Syndicate` instance. The core API is minimal: `tell()` for asynchronous fire-and-forget messages and `ask()` for request-reply with timeout. Actors can be organized hierarchically with parent-child relationships, supervision policies (restart, resume, escalate), and monitoring.

Beyond local concurrency, Spark offers opt-in distributed features: TCP routes with HMAC handshake, WebSocket routes for NAT traversal, authenticated federation for remote actor placement, and durable actors backed by SQLiteJournal. A separate `spark.workflow` package provides a higher-level abstraction for routing messages through a directed graph of processing nodes. The framework is in alpha (Development Status 3) and requires Python 3.13.

Use it for:

- Build concurrent services where independent tasks communicate via message passing instead of shared state.
- Create distributed systems with TCP or WebSocket routes connecting actor systems across network boundaries.
- Implement workflow pipelines using the `spark.workflow` layer to route messages through a sequence of processing nodes.
- Develop fault-tolerant systems with actor supervision, monitoring, and restart policies.
- Build NAT-traversal applications using the WebSocket relay for outbound-only connectivity.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Spark is an async-first actor framework for Python that lets you build concurrent and distributed systems by creating actors, sending messages with `tell()` (fire-and-forget) or `ask()` (request-reply), and managing them through a `Syndicate` instance.

Yes, if you are building a new concurrent or distributed system and are comfortable with alpha-stage software. The core API is clean, dependencies are minimal, and there are no known vulnerabilities. The project is actively maintained. Caution: verify that the supervision model and persistence layer meet your production requirements, and note that Python 3.13 is mandatory.

## Install

pip install spark
uv add spark
poetry add spark

## Installing Spark

Before you install: Installation is straightforward with no runtime dependencies for the core package. The project is actively maintained with a recent release and no known vulnerabilities. Optional extras like cbor2 and websocket are available for structured payloads and networking features.

License in practice: MIT license is permissive and imposes no significant restrictions on use, modification, or distribution in commercial or private projects.

Quickstart:

pip install spark

from spark import Actor, Syndicate
from spark.core.message import Message

class Echo(Actor):
    async def process(self, message: Message) -> str:
        return f"echo:{message.content}"

async with Syndicate("app") as system:
    echo = await system.create_actor(Echo)
    print(await system.ask("hello", echo, timeout=1.0))

Requires Python 3.13 or later.

Verify before relying:

- Whether the actor supervision model (restart/resume/escalate) is suitable for your fault-tolerance requirements.
- Performance characteristics and scalability limits for the number of actors and message throughput.
- Whether SQLiteJournal persistence is production-ready or still experimental.
- Maturity level of TCP and WebSocket remote routes for production deployments.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 80.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

actor framework python, async message passing, distributed actor system, concurrent python actors, actor model concurrency, python actor framework, message-driven architecture, actor-model, async-concurrency, message-passing

[View on SkillFed](https://skillfed.io/packages/spark) · [View on PyPI](https://pypi.org/project/spark/)