metaflow-local-service
Track your Metaflow runs locally without setting up a database.
The problem
When you want Metaflow's service metadata — run tracking, artifact indexing, heartbeats, tag
mutation — you need a running metaflow-service backed by PostgreSQL. That's fine for production,
but for local development, sandboxes, or CI you're forced to choose between local mode (no HTTP
API, no resume across machines) and a heavyweight Postgres deployment. There's no middle ground.
Quick start
pip install metaflow-local-service
# Start the service and run your flow in one command
metaflow-local-service run python myflow.py run
The daemon starts automatically, sets METAFLOW_SERVICE_URL and
METAFLOW_DEFAULT_METADATA=service for your flow, and shuts down after 5 minutes of idle time.
Data is written to .metaflow/ in the current directory — the same format as local mode.
Install
pip install metaflow-local-service
Requires Python 3.9+ and Metaflow 2.12+.
Usage
Wrap a flow command
metaflow-local-service run python myflow.py run --max-workers 4
The daemon starts if it isn't already running, then runs your command with the service URL in the environment.
Manage the daemon manually
metaflow-local-service start # start in background
metaflow-local-service status # show PID, port, and URL
metaflow-local-service url # print just the URL, for scripting
metaflow-local-service stop # send SIGTERM
Scripting
export METAFLOW_SERVICE_URL=$(metaflow-local-service url)
export METAFLOW_DEFAULT_METADATA=service
python myflow.py run
How it works
The daemon wraps Metaflow's own LocalMetadataProvider behind the standard service HTTP API
(v2.5.0). Data is written directly to .metaflow/ on every request — no sync step, no separate
database. On resume, task IDs are seeded from existing files on disk so new tasks never collide
with previous ones.
See docs/architecture.md for the full layer diagram.
Configuration
| Environment variable | Default | Description |
|---|---|---|
METAFLOW_LOCAL_SERVICE_PORT |
0 (random) |
Port to bind |
METAFLOW_LOCAL_SERVICE_IDLE_TIMEOUT |
300 |
Seconds of heartbeat silence before shutdown |
METAFLOW_LOCAL_SERVICE_DEBUG |
"" |
Set to 1 to enable daemon logging |
See docs/configuration.md for the full reference.
Development
git clone https://github.com/npow/metaflow-local-service.git
cd metaflow-local-service
pip install -e ".[dev]"
pytest
Structural tests (AST-based layer boundary enforcement) run without metaflow installed:
pytest -m structural
License
1 maintainer
Metadata
1 maintainer
Release files for metaflow-local-service 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| metaflow_local_service-0.2.0.tar.gz | 27.9 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| metaflow_local_service-0.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 48.9 kB
Release files / metaflow_local_service-0.2.0.tar.gz
| Download URL | metaflow_local_service-0.2.0.tar.gz |
|---|---|
| Size | 27.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a6cbc221085b38ee2fc7dda4ff2bd3ec0e99ea3759ffc7e3fedc1404f7eedfea
|
|
BLAKE2b-256 checksum How to use checksums |
6c5a01769b195b566497234c7cdb91d9a459ccbb588ebcfc5268392e7ef05bce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 8, 2026.
Transparency logRelease files / metaflow_local_service-0.2.0-py3-none-any.whl
| Download URL | metaflow_local_service-0.2.0-py3-none-any.whl |
|---|---|
| Size | 20.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
078913af6f5231e11c5928e18bae1c29ab8c02c3c68b2bef55223de5b42eecec
|
|
BLAKE2b-256 checksum How to use checksums |
83554056db7f98cc6813fbd17fcaa97a39fc97b2c2574daa4c9d3f6f71a694c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 8, 2026.
Transparency logSecurity for metaflow-local-service 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for metaflow_local_service-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 8, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
