Skip to main content

kyrax

A fast excel file reader for Python and Rust.

Docs:

  • Python (local: make doc-serve)
  • Rust (local: cargo doc --open -p kyrax)

Stability

The Python library is considered production-ready. The API is mostly stable, and we avoid breaking changes as much as possible.

⚠️ The free-threaded build is still considered experimental

The Rust crate is still experimental, and breaking changes are to be expected.

Installation

# Lightweight installation (no PyArrow dependency)
pip install kyrax

# With Polars support only (no PyArrow needed)
pip install kyrax[polars]

# With Pandas support (includes PyArrow)
pip install kyrax[pandas]

# With PyArrow support
pip install kyrax[pyarrow]

# With all integrations
pip install kyrax[pandas,polars]

Quick Start

kyrax supports the Arrow PyCapsule Interface for zero-copy data exchange with libraries like Polars, without requiring pyarrow as a dependency. Use kyrax with any Arrow-compatible library without requiring pyarrow.

import kyrax

# Load an Excel file
reader = kyrax.read_excel("data.xlsx")
sheet = reader.load_sheet(0)  # Load first sheet

# Use with Polars (zero-copy, no pyarrow needed)
import polars as pl
df = pl.DataFrame(sheet)  # Direct PyCapsule interface
print(df)

# Or use the to_polars() method (also via PyCapsule)
df = sheet.to_polars()
print(df)

# Or access the raw Arrow data via PyCapsule interface
schema = sheet.__arrow_c_schema__()
array_data = sheet.__arrow_c_array__()

Traditional usage (with pandas/pyarrow)

import kyrax

reader = kyrax.read_excel("data.xlsx")
sheet = reader.load_sheet(0)

# Convert to pandas (requires `pandas` extra)
df = sheet.to_pandas()

# Or get pyarrow RecordBatch directly
record_batch = sheet.to_arrow()

Working with tables

reader = kyrax.read_excel("data.xlsx")

# List available tables
tables = reader.table_names()
print(f"Available tables: {tables}")

# Load a specific table
table = reader.load_table("MyTable")
df = pl.DataFrame(table)  # Zero-copy via PyCapsule, no pyarrow needed

Turbo Read (high-performance XLSX reader)

read_excel_turbo provides selective feature parsing for high-throughput XLSX loading:

import kyrax

# Open workbook for turbo reading
reader = kyrax.read_excel_turbo("data.xlsx")

# Selective loading: values, formulas, styles, merges, comments, etc.
sheet = reader.load_sheet("Sheet1", features=["values", "styles", "formulas"])

# Access Arrow columns, cell errors, style indices, formulas
arrow_data = sheet.to_arrow()
styles = sheet.style_indices()
formulas = sheet.formulas()

Turbo Write & Streaming Export

Declarative, high-speed XLSX writing and streaming export:

import kyrax
import numpy as np

# Declarative write from sheet dicts or NumPy float grid fast lane
arr = np.array([[1.0, 2.5], [3.0, 4.25]], dtype=np.float64)
kyrax.write_excel_turbo("output.xlsx", [{"name": "Data", "grid": arr}])

# Streaming write for large datasets.
# NOTE: "columns" takes columnar DATA — a list of column arrays, not header
# names. Headers go in the first entry of "rows".
kyrax.write_excel_turbo_stream(
    "large_output.xlsx",
    [{"name": "Sheet1", "columns": [[1.0, 2.0, 3.0], ["a", "b", "c"]]}]
)

Edit Mode (Byte-Preserving Round-Trip)

Modify worksheet cells while preserving non-<sheetData> XML structures (cols, mergeCells, conditionalFormatting, dataValidations) byte-for-byte:

import kyrax

# Load workbook in edit mode
wb = kyrax.load_workbook("existing.xlsx", edit_mode=True)
ws = wb["Sheet1"]

# Update cell value and apply cell styles
ws["A1"] = "New Header"
ws.set_cell_style(0, 0, font={"bold": True, "color": "FF0000"})

# Save byte-preserving changes
wb.save("existing_updated.xlsx")

Key Features

  • Zero-copy data exchange via Arrow PyCapsule Interface
  • High-speed Turbo engine - selective XLSX feature reading (read_excel_turbo), declarative writing (write_excel_turbo), and streaming (write_excel_turbo_stream)
  • Byte-preserving edit mode - edit cells while keeping original XML metadata intact (load_workbook(..., edit_mode=True))
  • Flexible dependencies - use with Polars (no PyArrow needed) or Pandas (includes PyArrow)
  • Seamless Polars integration - pl.DataFrame(sheet) and sheet.to_polars() work without PyArrow via PyCapsule interface
  • High performance - written in Rust with calamine, rayon, and Apache Arrow
  • Memory efficient - lazy loading, zero-copy NumPy/PyArrow paths, and optional eager evaluation
  • Type safety - automatic type inference with manual override options

Contributing & Development

Prerequisites

You'll need:

  1. Rust - Rust stable or nightly
  2. uv - Fast Python package manager (will install Python 3.10+ automatically)
  3. git - For version control
  4. make - For running development commands

Python Version Management: uv handles Python installation automatically. To use a specific Python version:

uv python install 3.13  # Install Python 3.13
uv python pin 3.13      # Pin project to Python 3.13

Quick Start

# Clone the repository (or from your fork)
git clone <repository-url>
cd nextexcel

# First-time setup: install dependencies, build debug version, and setup pre-commit hooks
make setup-dev

Verify your installation by running:

make

This runs a full development cycle: formatting, building, linting, and testing

Development Commands

Run make help to see all available commands, or use these common ones:

make all          # full dev cycle: format, build, lint, test
make install      # install with debug build (daily development)
make install-prod # install with release build (benchmarking)
make test         # to run the tests
make lint         # to run the linter
make format       # to format python and rust code
make doc-serve    # to serve the documentation locally

Useful Resources

Benchmarking

For benchmarking, use make benchmarks which automatically builds an optimised wheel. This is required for profiling, as dev mode builds are much slower.

Speed benchmarks

make benchmarks

Memory profiling

mprof run -T 0.01 python python/tests/benchmarks/memory.py python/tests/benchmarks/fixtures/plain_data.xls

Creating a release

  1. Create a PR containing a commit that only updates the version in Cargo.toml.
  2. Once it is approved, squash and merge it into main.
  3. Tag the squashed commit, and push it.
  4. The release GitHub action will take care of the rest.

Dev tips

  • Use cargo check to verify that your rust code compiles, no need to go through maturin every time
  • cargo clippy = 💖
  • Careful with arrow constructors, they tend to allocate a lot
  • mprof and time go a long way for perf checks, no need to go fancy right from the start

Metadata

Release files for kyrax 1.0.7

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

Source distribution (sdist)

Source distribution for kyrax 1.0.7
File Size Uploaded Provenance Actions
kyrax-1.0.7.tar.gz 795.7 kB Without provenance Details for kyrax-1.0.7.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for kyrax 1.0.7
File Actions
kyrax-1.0.7-cp314-cp314t-win_amd64.whl CPython 3.14 CPython 3.14 free-threading Windows x86-64 Details for kyrax-1.0.7-cp314-cp314t-win_amd64.whl
kyrax-1.0.7-cp314-cp314t-musllinux_1_2_x86_64.whl CPython 3.14 CPython 3.14 free-threading Linux musl 1.2+ x86-64 Details for kyrax-1.0.7-cp314-cp314t-musllinux_1_2_x86_64.whl
kyrax-1.0.7-cp314-cp314t-musllinux_1_2_aarch64.whl CPython 3.14 CPython 3.14 free-threading Linux musl 1.2+ ARM64 Details for kyrax-1.0.7-cp314-cp314t-musllinux_1_2_aarch64.whl
kyrax-1.0.7-cp314-cp314t-manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 free-threading Linux glibc 2.28+ x86-64 Details for kyrax-1.0.7-cp314-cp314t-manylinux_2_28_x86_64.whl
kyrax-1.0.7-cp314-cp314t-manylinux_2_28_aarch64.whl CPython 3.14 CPython 3.14 free-threading Linux glibc 2.28+ ARM64 Details for kyrax-1.0.7-cp314-cp314t-manylinux_2_28_aarch64.whl
kyrax-1.0.7-cp314-cp314t-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 free-threading macOS 11.0+ ARM64 Details for kyrax-1.0.7-cp314-cp314t-macosx_11_0_arm64.whl
kyrax-1.0.7-cp314-cp314t-macosx_10_12_x86_64.whl CPython 3.14 CPython 3.14 free-threading macOS 10.12+ x86-64 Details for kyrax-1.0.7-cp314-cp314t-macosx_10_12_x86_64.whl
kyrax-1.0.7-cp310-abi3-win_arm64.whl CPython 3.10 abi3 Windows ARM64 Details for kyrax-1.0.7-cp310-abi3-win_arm64.whl
kyrax-1.0.7-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for kyrax-1.0.7-cp310-abi3-win_amd64.whl
kyrax-1.0.7-cp310-abi3-musllinux_1_2_x86_64.whl CPython 3.10 abi3 Linux musl 1.2+ x86-64 Details for kyrax-1.0.7-cp310-abi3-musllinux_1_2_x86_64.whl
kyrax-1.0.7-cp310-abi3-musllinux_1_2_aarch64.whl CPython 3.10 abi3 Linux musl 1.2+ ARM64 Details for kyrax-1.0.7-cp310-abi3-musllinux_1_2_aarch64.whl
kyrax-1.0.7-cp310-abi3-manylinux_2_28_x86_64.whl CPython 3.10 abi3 Linux glibc 2.28+ x86-64 Details for kyrax-1.0.7-cp310-abi3-manylinux_2_28_x86_64.whl
kyrax-1.0.7-cp310-abi3-manylinux_2_28_aarch64.whl CPython 3.10 abi3 Linux glibc 2.28+ ARM64 Details for kyrax-1.0.7-cp310-abi3-manylinux_2_28_aarch64.whl
kyrax-1.0.7-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for kyrax-1.0.7-cp310-abi3-macosx_11_0_arm64.whl
kyrax-1.0.7-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for kyrax-1.0.7-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 81.4 MB

Release files / kyrax-1.0.7.tar.gz

Download URL kyrax-1.0.7.tar.gz
Size 795.7 kB
Tags Source
SHA-256 checksum
How to use checksums
76937685600091a212f0040931f949c6d01bc52e67b9eddb59ff016035280296
BLAKE2b-256 checksum
How to use checksums
80bfe271761dcf16adedba34abb5fd6a450e8b5bdd57974d96a1c734a6655d79
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp314-cp314t-win_amd64.whl

Download URL kyrax-1.0.7-cp314-cp314t-win_amd64.whl
Size 5.1 MB
Tags CPython 3.14 CPython 3.14 free-threading Windows x86-64
SHA-256 checksum
How to use checksums
89db5fc75d70f165319200eae2e7df4d625377fac4c416ce554733b8a6f98473
BLAKE2b-256 checksum
How to use checksums
1edd6a0d79245a50000913f41e0011408cc00b03a05d62f6c82c19b207c01eee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp314-cp314t-musllinux_1_2_x86_64.whl

Download URL kyrax-1.0.7-cp314-cp314t-musllinux_1_2_x86_64.whl
Size 5.9 MB
Tags CPython 3.14 CPython 3.14 free-threading Linux musl 1.2+ x86-64
SHA-256 checksum
How to use checksums
9e534ed93d941383105b28b1a59238d598f2746d6bbe67b86cd4b0d0a1a78ba5
BLAKE2b-256 checksum
How to use checksums
77e9626f6adcb95f81c7d2955adddbefc08447eb59cdd4ceccebbed0b2dd0fcf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp314-cp314t-musllinux_1_2_aarch64.whl

Download URL kyrax-1.0.7-cp314-cp314t-musllinux_1_2_aarch64.whl
Size 5.7 MB
Tags CPython 3.14 CPython 3.14 free-threading Linux musl 1.2+ ARM64
SHA-256 checksum
How to use checksums
d10e029ba5395046f86690df8f3427db726c33663490277d9955df6a461a06ef
BLAKE2b-256 checksum
How to use checksums
7c13a7440c7731e5b5d908e49543037f4b7c0a6819dbf71c6847463e0052e6fa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp314-cp314t-manylinux_2_28_x86_64.whl

Download URL kyrax-1.0.7-cp314-cp314t-manylinux_2_28_x86_64.whl
Size 5.6 MB
Tags CPython 3.14 CPython 3.14 free-threading Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
3214d4d6e166bfbe0dfec2cead5ccf59c575624d5ff0fc3e18e2a7ddcfdd9f42
BLAKE2b-256 checksum
How to use checksums
67c218aea150a8e959e9248e1320ecdfa5296fb12ef449788021ad06a2040bac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp314-cp314t-manylinux_2_28_aarch64.whl

Download URL kyrax-1.0.7-cp314-cp314t-manylinux_2_28_aarch64.whl
Size 5.5 MB
Tags CPython 3.14 CPython 3.14 free-threading Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
7259912f52484e34ef6fada88d77ceb763e20c354de2c620f51077292acac01a
BLAKE2b-256 checksum
How to use checksums
61fd88c95d6a9d67c3b9e1360e1eb1b625a67b31fa2883b41728f2fa1cf20a3d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp314-cp314t-macosx_11_0_arm64.whl

Download URL kyrax-1.0.7-cp314-cp314t-macosx_11_0_arm64.whl
Size 4.9 MB
Tags CPython 3.14 CPython 3.14 free-threading macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
f3529556513caa1c6da2ade3cf0aade273f067c96a58a9febf4bfc5f4330486e
BLAKE2b-256 checksum
How to use checksums
068ca0c8276b479936d1b76cd9252f88aa47503ae74fbd9ad092f39004492c6e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp314-cp314t-macosx_10_12_x86_64.whl

Download URL kyrax-1.0.7-cp314-cp314t-macosx_10_12_x86_64.whl
Size 5.2 MB
Tags CPython 3.14 CPython 3.14 free-threading macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
7d11ff4bd4cd817c2c8c06af87fdcfc3a518e0c15f45abb657be2a5325a147ee
BLAKE2b-256 checksum
How to use checksums
85b5a3b8aa506d3955c1a6f582d8b1ff6c81a97fb7f533704798297fb1aab3e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp310-abi3-win_arm64.whl

Download URL kyrax-1.0.7-cp310-abi3-win_arm64.whl
Size 4.7 MB
Tags CPython 3.10 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
7226a3596fbcc4dee17e411d306614f17888de9d4d82c30013f5d409ce240a29
BLAKE2b-256 checksum
How to use checksums
765bce90f43d912d820cb6f8a2fe653bf7254fc8206e5459df10438ce3f8c30f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp310-abi3-win_amd64.whl

Download URL kyrax-1.0.7-cp310-abi3-win_amd64.whl
Size 5.1 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
ddefebda9630a11dc37527d66670972a3f844638752694af55abcfee203683fc
BLAKE2b-256 checksum
How to use checksums
a71d399a6cee3ccd0b085cabfcc025727fbb901bb23ea455dec4496ff37d3641
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp310-abi3-musllinux_1_2_x86_64.whl

Download URL kyrax-1.0.7-cp310-abi3-musllinux_1_2_x86_64.whl
Size 5.9 MB
Tags CPython 3.10 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
339ca0f745a32e26ed3662b53348031318a657fa0a021ffa824a12950d535ef1
BLAKE2b-256 checksum
How to use checksums
e5e64b6821ad8f6ff7102b2447c834075d06db68b59b40997141b577e64d1b6b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp310-abi3-musllinux_1_2_aarch64.whl

Download URL kyrax-1.0.7-cp310-abi3-musllinux_1_2_aarch64.whl
Size 5.7 MB
Tags CPython 3.10 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
1c97ff3d141cc5fce1f3a1621f2639d2cb34b78ce51e50e3695d597a6f598ae8
BLAKE2b-256 checksum
How to use checksums
33dab19f61bede60722950693cba9f3efac0011011b68b145025c7c5caf271b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp310-abi3-manylinux_2_28_x86_64.whl

Download URL kyrax-1.0.7-cp310-abi3-manylinux_2_28_x86_64.whl
Size 5.6 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
afc83e5d3d8c539d834fb25dd421a392bc0db4bcbff0a56e03452f7c2e8a7584
BLAKE2b-256 checksum
How to use checksums
270c8d87529146cbc288217959158cdbdfae96c97e489310b72520e402e75c43
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp310-abi3-manylinux_2_28_aarch64.whl

Download URL kyrax-1.0.7-cp310-abi3-manylinux_2_28_aarch64.whl
Size 5.5 MB
Tags CPython 3.10 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
72f449e41dfaba2849291f8b8e1d0e9e9d1040b67da39ff776b6f08780adfdc8
BLAKE2b-256 checksum
How to use checksums
658846c554c2ef189a6b379afbaf2362afd4c062a3b91a1965b5fdadfa4392ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp310-abi3-macosx_11_0_arm64.whl

Download URL kyrax-1.0.7-cp310-abi3-macosx_11_0_arm64.whl
Size 4.9 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
38d9316538bc5cbb19310c5f7cc95b56c2d415af152ac1b7d25ba144a624c69e
BLAKE2b-256 checksum
How to use checksums
6c4edc03bf797af2937cd3d5ec5f105c58eb8947b5b6c85de75e6cd4938b2030
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / kyrax-1.0.7-cp310-abi3-macosx_10_12_x86_64.whl

Download URL kyrax-1.0.7-cp310-abi3-macosx_10_12_x86_64.whl
Size 5.2 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
18c0b11afacacce4abcb34d18b34f3244a48357a9a3264e11f05e0f3c789a355
BLAKE2b-256 checksum
How to use checksums
9d76c57f18c2a62a965ad1af5fe4597f5b97bcff6bd45c4b7e3f195d7206358e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Security for kyrax 1.0.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.

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.

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