Skip to main content

Ursa

Polars-shaped dataframes for graph data.

Ursa is a graph analytics library for Python. You write a query the way you write a Polars query. A Rust engine runs it: Apache Arrow for the data, DataFusion for the plan, and parallel, deterministic kernels for the algorithms.

There is no Graph object. An edge table is the graph. Every operation returns a table.

Documentation: https://cldixon.github.io/ursa/

Install

pip install ursa-graph     # then: import ursa
# or
uv add ursa-graph

The package on PyPI is ursa-graph. The import name is ursa. Wheels include the compiled core, so you need no Rust toolchain. Python 3.10 or later.

polars is optional. Install pip install 'ursa-graph[polars]' for .to_polars() and ur.from_polars(). Data crosses the boundary as Arrow either way.

Try it

Paste this into a Python session. It needs no files and no network.

import ursa as ur

edges = ur.datasets.load_karate()   # 34 nodes, 78 edges, bundled with the package

top = (
    edges.nodes()
    .with_columns(
        degree=ur.degree(edges, direction="both"),
        triangles=ur.triangle_count(edges),
        community=ur.louvain(edges, seed=1),
    )
    .sort("degree", descending=True)
    .head(5)
    .collect()          # one query in the engine; the result is Arrow data
)
print(top)
shape: (5, 4)
┌───────┬────────┬───────────┬───────────┐
│ id    ┆ degree ┆ triangles ┆ community │
│ ---   ┆ ---    ┆ ---       ┆ ---       │
│ int64 ┆ uint32 ┆ uint32    ┆ uint32    │
╞═══════╪════════╪═══════════╪═══════════╡
│ 33    ┆ 17     ┆ 15        ┆ 2         │
│ 0     ┆ 16     ┆ 18        ┆ 0         │
│ 32    ┆ 12     ┆ 13        ┆ 2         │
│ 2     ┆ 10     ┆ 11        ┆ 0         │
│ 1     ┆ 9      ┆ 12        ┆ 0         │
└───────┴────────┴───────────┴───────────┘

To run the same query over your own data, change the first line:

edges = ur.scan_edges("edges.parquet", src="from_id", dst="to_id")

Nothing after that line changes. See the quickstart.

What it does

  • A dataframe API. with_columns, filter, sort, select, group_by, join. Lazy until collect(). If you know Polars, you know the shape.
  • The standard algorithms. Degree, PageRank, connected components, triangle count, clustering coefficient, closeness, betweenness, Louvain, label propagation. Each with a weighted form, where a weight is an expression over edge columns. Neighbour aggregation. Hops, shortest paths, and random walks.
  • Your data, where it is. Parquet and CSV, local or on S3, GCS, and Azure. Polars, pandas, pyarrow, NetworkX, NumPy, and SciPy in memory. Arrow in, Arrow out, with no copies.
  • Results you can check. Every kernel is deterministic on any thread count. Each one is pinned to the NetworkX call it matches, and the test suite checks it.

Ursa is version 0.4 and in active development. The Limits page lists what does not run yet.

How it is built

Layer Language Role
python/ursa Python The API. Builds a plan.
ursa-plan Rust Turns the plan into one DataFusion query, with graph operations as plan nodes.
ursa-core Rust The CSR topology index and the kernels. Parallel with rayon; compiles for wasm32 without it.
ursa-py Rust PyO3 bindings. Arrow crosses as zero-copy capsules; the GIL is released during compute.

The design document is design/SPEC.md.

Develop

uv sync                  # builds the extension and installs the dev tools
uv run pytest            # the Python suite, including every example in the docs
cargo test --workspace   # the Rust suites
uv run ruff check . && uv run ty check

uv sync --group docs && uv run zensical serve   # the documentation site, served locally

The docs are in docs/, built with Zensical and served by GitHub Pages. Every ```python block in them runs in the test suite, so an example that stops working fails CI. The benchmark harness is in benchmarks/.

License

MIT OR Apache-2.0.

Metadata

Release files for ursa-graph 0.4.0

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

Source distribution (sdist)

Source distribution for ursa-graph 0.4.0
File Size Uploaded Provenance Actions
ursa_graph-0.4.0.tar.gz 243.1 kB With provenance Details for ursa_graph-0.4.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for ursa-graph 0.4.0
File Actions
ursa_graph-0.4.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for ursa_graph-0.4.0-cp310-abi3-win_amd64.whl
ursa_graph-0.4.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.10 abi3 Linux glibc 2.17+ x86-64 Details for ursa_graph-0.4.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
ursa_graph-0.4.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.10 abi3 Linux glibc 2.17+ ARM64 Details for ursa_graph-0.4.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
ursa_graph-0.4.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for ursa_graph-0.4.0-cp310-abi3-macosx_11_0_arm64.whl
ursa_graph-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for ursa_graph-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 143.9 MB

Release files / ursa_graph-0.4.0.tar.gz

Download URL ursa_graph-0.4.0.tar.gz
Size 243.1 kB
Tags Source
SHA-256 checksum
How to use checksums
02aac947bf8b8539dea525ef3b4e2b9b1cf1a4f8e914e352184dc35fa9d23867
BLAKE2b-256 checksum
How to use checksums
4f897960fbd03f812faa7ed4a607fdbf34cbb8dc877edc30a26970864ec32166
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 18, 2026.

Transparency log

Release files / ursa_graph-0.4.0-cp310-abi3-win_amd64.whl

Download URL ursa_graph-0.4.0-cp310-abi3-win_amd64.whl
Size 30.4 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
48c2aaed832f4f3164327df64983d2c5aaa59cffc602eba6eb2581586cddaa9f
BLAKE2b-256 checksum
How to use checksums
15868c7ed731775608c3dd934a8fd2f3e23d6bb5519253913347b1cee6078529
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 18, 2026.

Transparency log

Release files / ursa_graph-0.4.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL ursa_graph-0.4.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 30.4 MB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
12a73a2a961ef8c5d5976959459444704ba657e4ea1addf1dcfc1ea61a5674c9
BLAKE2b-256 checksum
How to use checksums
d08350eea9603a8668f2990f9a6449b86e43b81f4a5c8902d463ebd2f1d88b31
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 18, 2026.

Transparency log

Release files / ursa_graph-0.4.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL ursa_graph-0.4.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 26.3 MB
Tags CPython 3.10 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
cc599c79c9034d2935889ed5017cae0d5bd05e365d285cfe408c1bba693ab4d3
BLAKE2b-256 checksum
How to use checksums
6cca7e22ad9fc712bcb73325689832fdfb3400af1db8b4c9d75f129a777f91e7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 18, 2026.

Transparency log

Release files / ursa_graph-0.4.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL ursa_graph-0.4.0-cp310-abi3-macosx_11_0_arm64.whl
Size 27.4 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
395bc4ff96756d24b17ec79747d1ad93fb69661db18c0132195b2a22484aff67
BLAKE2b-256 checksum
How to use checksums
07ba2078b02736cab0306ac99828dcd63c11aeccf5811438c0e06cfe91134202
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 18, 2026.

Transparency log

Release files / ursa_graph-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl

Download URL ursa_graph-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl
Size 29.3 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
ede62eac6e2c809c376e2d6b487629683825ddf38dcfca62e4be9a7c57c5e596
BLAKE2b-256 checksum
How to use checksums
d0e106235e5c114a1e6da1f74efcab2b12b193eb96a81ab02915da8a2fbefac5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 18, 2026.

Transparency log

Security for ursa-graph 0.4.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 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for ursa_graph-0.4.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 Oct 18, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page