barca

Runs Python functions as a dependency graph and caches their results.

Python Rust

Barca runs Python functions as a dependency graph and caches their results.

You mark 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 needs to run, and runs it in Python worker processes. Every result is a file under .barca/, and an asset runs again only when its code, the project code it calls, or its inputs change; sensors and tasks run every time. There is no server to run and no configuration file to write; barca serve adds schedules, an HTTP API and a web UI when you want them.

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.0s
Run 14d44f778fda | all assets in 0.073s (2 steps, 1 phase)

.barca/artifacts/pipeline.py--summary/2d10c4c5ef45...json
  {
    "count": 3,
    "total": 6
  }

$ barca get pipeline.py
Run 14d7f1ead5ae | all assets in 0.019s (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 02:41:21 UTC 0.00s  3 rows x 1 col  -
summary   asset  stale   changed: code  success 2026-10-21 02:41:21 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 14d473c6a264 | got 'summary' in 0.076s (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.

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 the artifact's rows and columns.
`barca logs [RUN_ID]`	A run's recorded step stdout, without progress messages; the most recent run without an id.
`barca history`	Recent runs.
`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 (experimental).
`barca doctor [files...]`	Check the project, Python, cache, metadata, stores and capacity without running steps.
`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 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.

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.

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`	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 and Prefect; benchmarks/RESULTS.md records measurements with their date and machine. Barca is pre-1.0: a breaking change to the CLI ships in a minor release with a "Breaking" line in the release notes.

License

MIT

Metadata

Release files for barca 0.29.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for barca 0.29.1
File	Size	Uploaded	Provenance
barca-0.29.1.tar.gz	1.9 MB	Oct 21, 2026	Without provenance	Details

Built distributions (wheels)

Table of built distributions (wheels) for barca 0.29.1
File	Interpreter	ABI	Platform	Reset
barca-0.29.1-py3-none-musllinux_1_2_x86_64.whl 14.3 MB Oct 21, 2026 Without provenance	Python 3	none	Linux musl 1.2+ x86-64	Details
barca-0.29.1-py3-none-musllinux_1_2_aarch64.whl 13.2 MB Oct 21, 2026 Without provenance	Python 3	none	Linux musl 1.2+ ARM64	Details
barca-0.29.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 14.1 MB Oct 21, 2026 Without provenance	Python 3	none	Linux glibc 2.17+ x86-64	Details
barca-0.29.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 13.3 MB Oct 21, 2026 Without provenance	Python 3	none	Linux glibc 2.17+ ARM64	Details
barca-0.29.1-py3-none-macosx_11_0_arm64.whl 12.8 MB Oct 21, 2026 Without provenance	Python 3	none	macOS 11.0+ ARM64	Details

Total release size: 69.6 MB

Release files / barca-0.29.1.tar.gz

Download URL	barca-0.29.1.tar.gz
Size	1.9 MB
Tags	Source
SHA-256 checksum How to use checksums	`f73555e228f88ac5d20a367987bc550bb6fc7df62067321678a99da8ff54fa05`
BLAKE2b-256 checksum How to use checksums	`0ac234e7cc4297b4f38a52bd605c911692ee08d15b21036e501eebbf44f11f71`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / barca-0.29.1-py3-none-musllinux_1_2_x86_64.whl

Download URL	barca-0.29.1-py3-none-musllinux_1_2_x86_64.whl
Size	14.3 MB
Tags	Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum How to use checksums	`8a919a133fc80613c7841109f36906f492d4d768d94d9378f2fda949145acb8b`
BLAKE2b-256 checksum How to use checksums	`a23dff7f11bedd6e6f4f8e859cb71b79c2631fa4afe7b5f6a980beb238824f1c`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / barca-0.29.1-py3-none-musllinux_1_2_aarch64.whl

Download URL	barca-0.29.1-py3-none-musllinux_1_2_aarch64.whl
Size	13.2 MB
Tags	Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum How to use checksums	`ccdef1a8a0d6da7fa351f1e862464f4422b77fb2d3de49dbd5ffcb3c92530719`
BLAKE2b-256 checksum How to use checksums	`b7a39318fe252a427ccee274967d3acd3b3af92278580c62830a50605f88e2a6`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / barca-0.29.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	barca-0.29.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	14.1 MB
Tags	Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum How to use checksums	`6c92e20659fe9b97b2487bdd26d56c3a9c9196a1c6fa69a57b96852261753b85`
BLAKE2b-256 checksum How to use checksums	`a68eea3659dad79c7cf3a4f451720f9c599afe04300b45caaa193c91309e3e26`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / barca-0.29.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	barca-0.29.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size	13.3 MB
Tags	Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum How to use checksums	`502c7af01c294e70c02040ef7c8833c829512b267aa1a84c2dc2329c08e0dc05`
BLAKE2b-256 checksum How to use checksums	`d672ccc8b1f69e5b173a0e05775c04e153f153b21080694473236441ec017f1c`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Release files / barca-0.29.1-py3-none-macosx_11_0_arm64.whl

Download URL	barca-0.29.1-py3-none-macosx_11_0_arm64.whl
Size	12.8 MB
Tags	Python 3 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`cf7e71ddf1ef2ccef4f0be9f58a10e93939a6802cf7b043edec5c31f419a1236`
BLAKE2b-256 checksum How to use checksums	`29e54e0a3a034049f144bfaf637cb127709b68702e7fe07a9e8f81de41fc781e`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Security for barca 0.29.1

Report project as malware

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.