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.6

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.6
File Size Uploaded Provenance Actions
kyrax-1.0.6.tar.gz 792.5 kB Without provenance Details for kyrax-1.0.6.tar.gz

Built distributions (wheels)

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

Total release size: 81.5 MB

Release files / kyrax-1.0.6.tar.gz

Download URL kyrax-1.0.6.tar.gz
Size 792.5 kB
Tags Source
SHA-256 checksum
How to use checksums
ef5824861509c808f9e8f5fe916f2e8b50d1987212063ebd6189ee2f8159738f
BLAKE2b-256 checksum
How to use checksums
35d254c756f032a9486c0d9f7668913ade0b79a2a4a3b0960a81302b1fbf359f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
6d770cdebc7dcb3e1e571d1f7770be4708c12a0447f0e9f60441bbb7600fa825
BLAKE2b-256 checksum
How to use checksums
ee4c3b3fc53b2cb58c8e882bba10d4ebda3c7fd000ac9e9f8923fce647a4d36a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
acea75d6d398622e70a651e9f48d20d6d4d322e2f247fab904c544445539f0ee
BLAKE2b-256 checksum
How to use checksums
112fe695f971c8c99ba9283b13dc578ca018b9c2c0b6ad729db45a77a9cbe081
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
4424c6e528b8597ee25b8560742de0b55f572bc6e6bbda895ae78da8a080161c
BLAKE2b-256 checksum
How to use checksums
6807b63104c1c9e466336665174d9e62f2732fdf8d872418ebd45617884e47d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
c609a8e75489e1571d8d6001a6bef00fef2e52ffb759711e6e1e0492fc937b6c
BLAKE2b-256 checksum
How to use checksums
67098aec68b9872a8a028c25905d002a7e17ea92b168dfa6c32235923fc83bfa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
df044b7c0b67975178d0b2a97fd4a875ed001b9307a024b72358e8cb5c7f4bdd
BLAKE2b-256 checksum
How to use checksums
5a3e3d6d5d217301fcd27746e92886881ef9bf2bb4c6e0c7e70626ec1fcb1b24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
4ace2cc474537a4e30da5261d4158ca380d4b07c75836f7ebbd2dde74a7937b4
BLAKE2b-256 checksum
How to use checksums
22e83f8458900c9cbb1cbd1e76cfc1ca288456b502edd6ddd334306833efbdcf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
e148843b2e788d968bcbb45bac41de992a52c6365d0faf37248c8a7b68229d8d
BLAKE2b-256 checksum
How to use checksums
33eaa783b6d632d49df139566a73182e84d7962980e8f673a71328824b23d2d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-cp310-abi3-win_arm64.whl
Size 4.8 MB
Tags CPython 3.10 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
0e8380f5f9243a8dc2a8b30117bebc6c39e515ff47ec34afbf91363205a20511
BLAKE2b-256 checksum
How to use checksums
2cdfd808696fac195b4661b0207196733964ca5867c7648f30dbf55f8dc3dcbf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

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

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

Download URL kyrax-1.0.6-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
71fded939bb78fd4c3b6748c9f07d029bcc717536d8ddd3c32b909bd4638d21a
BLAKE2b-256 checksum
How to use checksums
ddd83c3f6428b281dcbaf5d7d4f6450dcefbc5c16b0d58390f7a055ca7303b20
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
0c304cb578815956b74c6cbfad07e29131d38c4c941bdb993aacd9dc7936f2e0
BLAKE2b-256 checksum
How to use checksums
01a1a33058d1afa68303ef2329379c6b0d60ffa7be07be685b5643a13ed16e97
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
f596c252cfd54734e5a83d481b5cbe1c65c3ae557fa75bcce2b2186203cee68d
BLAKE2b-256 checksum
How to use checksums
59b47537ad5c196d028989ed83f24b774f1434daa91d031b9694efcaaa097293
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
00e1bebcef2049b1b0ed80f472f8a1618218005f2b50c3c59996892aa2f4f3ef
BLAKE2b-256 checksum
How to use checksums
e329f3ed26d43c10ddb7b2103bbb73a439471d6a9332a0cad45c1261a7025653
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
2f829f164ca75f2414d4aed86829eab89837b78bac9213a7ed0eee533604586f
BLAKE2b-256 checksum
How to use checksums
36d7b02ede5f4e6ffd969155a9edb680fc7b8ecce5624b68cbf617b704ac4478
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL kyrax-1.0.6-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
2b07ed69fe3ed9f63ca941d1e5f1f2528976d81be044258bcfea53575b8710d5
BLAKE2b-256 checksum
How to use checksums
1dcb823f7e8fc25a41f0845a431009ef0253b11b172df1dd534e40d94471e80f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Security for kyrax 1.0.6

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