barca
An embedded orchestrator for Python: a binary and a directory, like DuckDB or SQLite.
No server, no config; it runs what changed and caches the rest.
Docs · Guide · Changelog · Contributing
Status: pre-1.0. A breaking change to the CLI ships in a minor release with a "Breaking" line in the changelog.
You mark Python functions with @asset, @sensor or @task and declare their inputs. The
barca binary, written in Rust, reads your source without importing it, works out what is
stale, and runs it in Python worker processes. Every result is a file under .barca/.
barca serve adds cron schedules, an HTTP API and a web UI when you want them.
Why barca
- Reads your code without importing it. The graph comes from parsing the source, so
list,statusand--dry-rundo not run your modules. - One install, no server.
uv add barcabrings the binary, the decorators and a Python API; the state is one directory,.barca/. - Recomputes only what changed. An asset runs again when its code, the project code it calls, or its inputs change; everything else comes from the cache.
- Milliseconds of overhead. A one-asset pipeline runs in 64 ms from process start to exit, against 1.07 s for Dagster and about 5 s for Prefect and Airflow on the same machine (comparison); 0.28.3 then cut barca's time for it from 86 to 47 ms.
Install
uv add barca # or: pip install barca
Python 3.12 or later. The wheel contains the barca binary, the decorators and a Python API;
wheels are published for macOS on Apple Silicon and for Linux on x86-64 and arm64, glibc and
musl. Barca runs your steps with the Python of the environment it is installed in, or python3
on PATH.
Optional extras: barca[parquet] (pyarrow, for DataFrames), barca[sql] (DuckDB, for
barca sql), barca[datadog], and barca[s3], barca[gcs], barca[azure] or
barca[remote] for a remote store.
Example
# pipeline.py
from barca import asset
@asset()
def raw_data() -> list[dict]:
return [{"x": 1}, {"x": 2}, {"x": 3}]
@asset(inputs={"data": raw_data})
def summary(data: list[dict]) -> dict:
return {"count": len(data), "total": sum(d["x"] for d in data)}
$ barca get pipeline.py
[barca] 2/2 steps | done in 0.1s
Run dc8e11f9d49e | all assets in 0.064s (2 steps, 1 phase)
.barca/artifacts/pipeline.py--summary/2d10c4c5ef45...json
{
"count": 3,
"total": 6
}
$ barca get pipeline.py
Run dc8f6d863e28 | all assets in 0.003s (0 steps, 1 phase)
...
get prints the path of each result, with a preview of a small json value in a terminal. The
second run executes 0 steps: both results come from the cache.
Change summary (say, "total" becomes "sum") and ask what is stale. status runs nothing:
$ barca status
NAME KIND STATE WHY LAST RUN SHAPE DEPS
raw_data asset cached materialized success 2026-10-21 19:52:47 UTC 0.00s 3 rows x 1 col -
summary asset stale changed: code success 2026-10-21 19:52:47 UTC 0.00s dict (2 keys) raw_data
1 cached, 1 stale, 0 never run, 0 partial, 0 unknown, 0 always run
$ barca get summary
[barca] 1/2 steps | done in 0.0s
Run dc8c75a5f03a | got 'summary' in 0.034s (1 step, 1 phase)
...
Only summary runs again; raw_data comes from the cache. To recompute by hand, name the
assets: barca get summary --refresh raw_data (and everything downstream of it), or
--refresh-all. Do not delete files under .barca/ to force a recompute.
An asset that reads a file, a bucket or a table in its own body has the same code and inputs
on every run, so it is served from cache even after the data changes. Data from outside comes
in through a @sensor, which runs every time and returns something identifying the current
version; the assets that take it as an input re-run only when that value changes:
import hashlib
from pathlib import Path
from barca import asset, sensor
@sensor()
def orders_version() -> tuple[bool, str]:
return True, hashlib.md5(Path("orders.csv").read_bytes()).hexdigest()
@asset(inputs={"version": orders_version})
def orders(version: str) -> list:
return Path("orders.csv").read_text().splitlines()[1:]
More: barca docs cache ("External data that changes in place"), which also lists what the
run hash does not see.
barca serve runs the same files on cron schedules, with an HTTP API and a web UI that shows
what is cached, running and queued:
From Python, barca.get("summary") returns the value, and the decorators return the function
unchanged, so steps can be called and unit tested as ordinary Python.
Commands
The target comes first, then files or directories. Both are optional: with no files, barca
reads every .py file under the project root that imports barca (barca docs discovery).
get is for assets and uses the cache; run is for tasks, which always run, and their
upstream assets come from the cache. Every barca <command> --help ends with runnable
examples.
| Command | What it does |
|---|---|
barca get [target] [files...] |
Bring assets up to date and print their artifact paths; -o value prints the values. No target: every asset and sensor. |
barca run <task> [files...] |
Run a task, or several (a,b), and what they depend on. |
barca list [files...] |
Every asset, sensor and task, with its kind, freshness and inputs. |
barca status [target] [files...] |
Per node: cached or stale and why, the last run (and its error), the artifact's rows and columns, and a schedule's state; --problems keeps what needs attention. |
barca logs [RUN_ID] |
A run's recorded step stdout and stderr, without progress messages; the most recent run without an id, -f to follow a running one, from a configured server too. |
barca history [RUN_ID] |
Recent runs, filtered by --status, --target, --triggered-by and --since, each failed one with its failing step and error; with a run id, its steps, errors and tracebacks. |
barca stats <target> [files...] |
Timing and re-execution statistics for one asset. |
barca sql "<query>" [files...] |
Query cached results with DuckDB; each asset is a view, barca's records are barca.runs, barca.materializations and barca.nodes; with a server, the team's results (experimental). |
barca doctor [files...] |
Check the project, Python, cache, metadata, stores and capacity without running steps, and a configured server: its version, store, load errors, schedules and the runs not posted to it. |
barca plan [files...] |
The execution plan as JSON, with the capacity and step weights (experimental). |
barca gc |
Evict cached results to keep .barca/ under its size limit (barca also does this after every run). |
barca serve [files...] |
Cron scheduler, HTTP API and web UI; --server on other commands runs them there. |
barca queue [pause|resume] --server |
A server's run queue (kept across restarts); pause or resume it before a deploy. |
barca state backups / barca state restore / barca state reset |
List the metadata backups, put one back in place of the local database, or start it over (experimental; nothing is deleted). |
barca docs [topic] |
The manual, compiled into the binary. |
barca version |
Print the version (also barca --version). |
Common flags on get and run: --refresh a,b, --no-cascade, --refresh-all,
--dry-run, --env <name> (a separate cache and history), --partition key=value (only those
keys, across the whole run; also on barca plan).
Scripts and AI agents. Results go to stdout: a table or summary in a terminal, JSON when
piped or captured (--json and --pretty override). Progress and errors go to stderr; in JSON
mode an error is one JSON line with error, code, kind and remediation. Exit codes: 0
ok, 1 a step failed, 2 usage error, 3 barca or infrastructure failure, 130 cancelled.
An agent should load SKILL.md, also printed by barca docs skill.
More
barca docs lists the manual's topics and barca docs <topic> prints one; start with
overview. The site, barca.sh, has the same material plus a guide and
patterns.
| Topic | Manual | Site |
|---|---|---|
| What is cached, the run hash, artifacts, environments, disk use | barca docs cache |
Guide |
| Decorators, inputs, freshness, retries | barca docs assets, barca docs tasks |
Decorators API |
| Output formats and large inputs (parquet, CSV, lazy DuckDB and polars) | barca docs types, barca docs big-inputs |
Guide: large inputs |
Partitions: fan-out over keys, fan-in with collect |
barca docs partitions |
Guide: partitions |
Schedules, barca serve and its HTTP API |
barca docs scheduling |
Scheduling, Deploying |
| Server mode: one server as the team's ledger | barca docs server-mode |
Share with a team, Server mode |
| A remote store (S3, GCS, Azure): this machine's backup and read-through cache | barca docs remote |
Remote storage |
| Datadog traces, Slack notifications, JSON logs | barca docs telemetry |
Telemetry |
| Inspecting results: status, logs, sql | barca docs status, barca docs logs, barca docs sql |
SQL |
| Scripts and AI agents | barca docs skill, barca docs agents |
Agent skill |
| The CLI contract: commands, flags, JSON schemas, exit codes, stability | barca docs contract |
CLI contract |
Development
git clone https://github.com/barca-orc/barca.git
cd barca
uv venv
source .venv/bin/activate
uv pip install maturin
maturin develop --uv --release --extras test # builds the binary and installs it into .venv
cargo test
See Architecture and
Contributing. benchmarks/ holds the same
pipelines written for barca, Dagster, Prefect and Airflow;
benchmarks/RESULTS.md records measurements with their date and
machine.
License
1 maintainer
Metadata
1 maintainer
Release files for barca 0.30.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 | |
|---|---|---|---|---|
| barca-0.30.0.tar.gz | 2.1 MB | Without provenance | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| barca-0.30.0-py3-none-musllinux_1_2_x86_64.whl | Python 3 | none | Linux musl 1.2+ x86-64 | Details |
| barca-0.30.0-py3-none-musllinux_1_2_aarch64.whl | Python 3 | none | Linux musl 1.2+ ARM64 | Details |
| barca-0.30.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details |
| barca-0.30.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details |
| barca-0.30.0-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
Total release size: 73.6 MB
Release files / barca-0.30.0.tar.gz
| Download URL | barca-0.30.0.tar.gz |
|---|---|
| Size | 2.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
946658a7e5db38875d6ed0a77c12e128a854d48e3b54156648e679532cb17afc
|
|
BLAKE2b-256 checksum How to use checksums |
96399201c50c95f6abb54aa130077545bb9d2fce1e072a93222f087681d558dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / barca-0.30.0-py3-none-musllinux_1_2_x86_64.whl
| Download URL | barca-0.30.0-py3-none-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 15.1 MB |
| Tags | Linux musl 1.2+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
790bceb1fa1bdec26a957ff5c0f560f0c0c5c980c6c7254e3f2cfaf1de9cd066
|
|
BLAKE2b-256 checksum How to use checksums |
827e1088d5fdead30fc6e5ef0d8de517b2d0c9a935a0a51496e3525274ad49f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / barca-0.30.0-py3-none-musllinux_1_2_aarch64.whl
| Download URL | barca-0.30.0-py3-none-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 13.9 MB |
| Tags | Linux musl 1.2+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
b4701c1ecf926d3278f9f1176ac018708d68e847ada5d99aa3417034706d5ff0
|
|
BLAKE2b-256 checksum How to use checksums |
81c7e7cdfa461cc903067a376ad18f97c344f02317f3f1977a53bb3265c3d751
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / barca-0.30.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | barca-0.30.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 15.0 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
2447a625ba63b87d7a543158d1fbbc469577c69a99c0ed9e12a61144fc531565
|
|
BLAKE2b-256 checksum How to use checksums |
7bc646bc4dc62aa5d071ebbb41680f981dc2e1a6bccb7f0768c4138663829724
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / barca-0.30.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | barca-0.30.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 14.0 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
256f9e491061bd4735e3992a0a6a91fc5fb50cbfee0feb5c3328278916df84e3
|
|
BLAKE2b-256 checksum How to use checksums |
b83a7c24fdad822d0db62135d8893f5a78798faa6926d0298107eeb323010f4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / barca-0.30.0-py3-none-macosx_11_0_arm64.whl
| Download URL | barca-0.30.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 13.6 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a89bd886e69b8cf4e3225743c189cca87d018a5231e832b263f3ebeeda5069c7
|
|
BLAKE2b-256 checksum How to use checksums |
a7a0344112d87b1f7a089080a81157e18ab47b9f7ac2a5491ca8df826a2c2561
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for barca 0.30.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.
