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
# 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.3 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.3.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.3.0
File Size Uploaded Provenance Actions
ursa_graph-0.3.0.tar.gz 202.3 kB With provenance Details for ursa_graph-0.3.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for ursa-graph 0.3.0
File Actions
ursa_graph-0.3.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for ursa_graph-0.3.0-cp310-abi3-win_amd64.whl
ursa_graph-0.3.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.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
ursa_graph-0.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.10 abi3 Linux glibc 2.17+ ARM64 Details for ursa_graph-0.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
ursa_graph-0.3.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for ursa_graph-0.3.0-cp310-abi3-macosx_11_0_arm64.whl
ursa_graph-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for ursa_graph-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 143.3 MB

Release files / ursa_graph-0.3.0.tar.gz

Download URL ursa_graph-0.3.0.tar.gz
Size 202.3 kB
Tags Source
SHA-256 checksum
How to use checksums
0a635a799cd472903ff12891401b93c02d2e0b0dd64c36a420a81d100fc1ed4c
BLAKE2b-256 checksum
How to use checksums
21b00e99f5d59bc303d6f350b88f3195b47118da2c98d3718d96b3cbac529449
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 8, 2026.

Transparency log

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

Download URL ursa_graph-0.3.0-cp310-abi3-win_amd64.whl
Size 30.2 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
fd60484fef7db66d9b8f10705c6da42795bce2423c05b820202a2f361edc390a
BLAKE2b-256 checksum
How to use checksums
96ed72c05ce9c5170570d3c6de8e1199e75200a35ac5dec40ae4ddde8d6c561c
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 8, 2026.

Transparency log

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

Download URL ursa_graph-0.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 30.3 MB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
067ca98735d5c2d996bd630a812f82bbd51f8a5f1a5e49fcf99fd312f59d52be
BLAKE2b-256 checksum
How to use checksums
75dc678f04adae60e147b7fabe3246a336d4cb5e31834de0e0c56e9f5a6c3c69
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 8, 2026.

Transparency log

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

Download URL ursa_graph-0.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 26.2 MB
Tags CPython 3.10 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
1454960dbb8ac955e6e7928bd46ae41157e4d7c2b620955d5393157f6112b349
BLAKE2b-256 checksum
How to use checksums
08fe775f2cc88d52cf462c792e24be88e119c2b8faede0f67cbf9398a90f9179
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 8, 2026.

Transparency log

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

Download URL ursa_graph-0.3.0-cp310-abi3-macosx_11_0_arm64.whl
Size 27.3 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
6278ab1268b09f98da3b50be82fd457f656a9946d80f8208b59cb0eb394298bc
BLAKE2b-256 checksum
How to use checksums
cfca856a1265ce03df85c6b57f3d6d4c77c1e9a6d1311e906311c679dd62c282
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 8, 2026.

Transparency log

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

Download URL ursa_graph-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl
Size 29.2 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
1447b96798e9ed31191875c2077199dee050c029af8d48931846302cdfbe51d9
BLAKE2b-256 checksum
How to use checksums
f1fc33a9004930fd8d0246a3e84b5cab1dafe87ff96a6ba2859036f5e0425f9d
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 8, 2026.

Transparency log

Security for ursa-graph 0.3.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.3.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 8, 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