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
Modern usage (recommended)
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)andsheet.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:
- Rust - Rust stable or nightly
- uv - Fast Python package manager (will install Python 3.10+ automatically)
- git - For version control
- 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
python/kyrax/_kyrax.pyi- Python API typespython/tests/- Comprehensive usage examples
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
- Create a PR containing a commit that only updates the version in
Cargo.toml. - Once it is approved, squash and merge it into main.
- Tag the squashed commit, and push it.
- The
releaseGitHub action will take care of the rest.
Dev tips
- Use
cargo checkto verify that your rust code compiles, no need to go throughmaturinevery time cargo clippy= 💖- Careful with arrow constructors, they tend to allocate a lot
mprofandtimego 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)
| 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)
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.