---
id: mirakuru
version: "3.0.2"
license: LGPL-3.0-or-later
license_treatment: copyleft
maintenance: active
---

# mirakuru — Process executor (not only) for tests.

License: copyleft · Maintenance: active · Downloads: 3.6M/mo

## What it is and what it does

Mirakuru is a process orchestration library for functional and integration tests. It solves the problem of coordinating startup of external services—databases, message queues, APIs, web servers—by starting them and blocking until they signal readiness (via TCP connection, HTTP response, output banner, Unix socket, or .pid file) before your test code runs. This eliminates race conditions where tests try to connect to a service that hasn't finished initializing.

The library provides seven executor classes for different readiness signals: SimpleExecutor (no wait), OutputExecutor (watches stdout for a marker), TCPExecutor (tries TCP connection), HTTPExecutor (checks HTTP status), UnixSocketExecutor (Unix socket readiness), PidExecutor (waits for .pid file), and a base Executor class. Each executor wraps a command string or list, starts the process, polls for readiness, and provides start() and stop() methods. Executors also work as context managers for cleaner test setup/teardown.

Use it for:

- Start a PostgreSQL container in a test and wait until it accepts connections before running integration tests.
- Launch an HTTP API server and verify it responds to requests before running end-to-end tests.
- Orchestrate multiple services (Redis, Elasticsearch, a custom daemon) in a single test fixture with guaranteed startup order.
- Monitor a process's stdout for a 'ready' message and proceed only when that marker appears.
- Manage test cleanup by stopping all spawned processes in the correct order when tests complete.

## Worth the install?

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

Mirakuru starts external processes (databases, services, APIs) and waits until they are ready to accept connections or produce specific output before returning control to your code.

Yes. Mirakuru is actively maintained, has no security vulnerabilities, low install friction, and solves a genuine testing problem—eliminating flaky tests caused by timing races with external services. It is well-suited for integration and functional test suites that depend on external processes.

## Install

pip install mirakuru
uv add mirakuru
poetry add mirakuru

## Installing mirakuru

Before you install: Low friction: pure Python wheel with a single runtime dependency (psutil). Active maintenance with recent release (2026-02-11) and no known vulnerabilities.

License in practice: LGPL-3.0-or-later (copyleft): you may use this in proprietary code, but modifications to mirakuru itself must be shared under the same license.

Quickstart:

from mirakuru import TCPExecutor

redis = TCPExecutor('redis-server', host='localhost', port=6379)
redis.start()
# Redis is now ready
redis.stop()

Requires Python 3.10 or later; the external process being orchestrated must be installed and on PATH.

Verify before relying:

- Whether psutil is always available on all supported platforms or if there are OS-specific limitations.
- Timeout behavior and configurability when a process fails to reach readiness state.

## Package facts

- License: LGPL-3.0-or-later (copyleft)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 3.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

process orchestration testing, wait for service startup, external process management, integration test fixtures, TCP port readiness check, HTTP service readiness, process executor for tests, process-management, test-fixtures, service-readiness

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