# Getting started

> Install Hypaxel, write a first XLSX workbook, stream an Excel download from a web endpoint or the browser, and read a workbook back row by row.

Source: https://hypaxel.libs.vensas.de/docs/getting-started  
Last updated: 2026-11-20

This page takes you from choosing an implementation to a first workbook, a streamed HTTP download and a first read. Each language has its own guide with the full details; the examples here are the shortest working path.

## Choose your language

| Language | Package | Runtime | Engine | Reads | Guide |
| --- | --- | --- | --- | --- | --- |
| .NET | `Hypaxel`, `Hypaxel.AspNetCore` | .NET 8, 9, 10, 11 | native | yes | [/docs/dotnet](https://hypaxel.libs.vensas.de/docs/dotnet) |
| Rust | `hypaxel`, `hypaxel-axum` | Rust 1.85+ | native | yes | [/docs/rust](https://hypaxel.libs.vensas.de/docs/rust) |
| Python | `hypaxel` | CPython 3.10+ | Rust core (PyO3) | yes | [/docs/python](https://hypaxel.libs.vensas.de/docs/python) |
| Node.js | `hypaxel` | Node.js 22+ | Rust core (napi-rs) | not yet | [/docs/nodejs](https://hypaxel.libs.vensas.de/docs/nodejs) |
| Browsers | `hypaxel` | Chrome/Edge 96+, Firefox 79+, Safari 15+ | Rust core (WebAssembly) | not yet | [/docs/nodejs#browsers](https://hypaxel.libs.vensas.de/docs/nodejs#browsers) |
| Go | `github.com/vensas/hypaxel/go` | Go 1.26+ | native | yes | [/docs/go](https://hypaxel.libs.vensas.de/docs/go) |
| Java | `de.vensas:hypaxel` | Java 17+ | native | yes | [/docs/java](https://hypaxel.libs.vensas.de/docs/java) |
| PHP | `vensas/hypaxel` | PHP 8.2+ (64-bit, `ext-zlib`) | native | not yet | [/docs/php](https://hypaxel.libs.vensas.de/docs/php) |

The Python and Node.js packages call into the Rust core; in browsers, the Node.js package runs the same core as WebAssembly. The other five are independent implementations of the same design, so each runs without native libraries or extra runtime dependencies.

## Install

> **Not published yet:**
>
> No Hypaxel package is published to a registry yet. The commands below show the package names and coordinates that will be used once they are. Until then, build from source: the code is at [github.com/vensas/hypaxel](https://github.com/vensas/hypaxel), and each language guide has a "Building from source" section.

- **.NET:** packages `Hypaxel` (core writer) and `Hypaxel.AspNetCore` (HTTP response helpers).
- **Rust:** crates `hypaxel` (core writer) and `hypaxel-axum` (axum response type).

```bash
pip install hypaxel                        # Python
npm install hypaxel                        # Node.js
go get github.com/vensas/hypaxel/go        # Go
composer require vensas/hypaxel            # PHP
```

Java (Maven coordinates):

```xml
<dependency>
  <groupId>de.vensas</groupId>
  <artifactId>hypaxel</artifactId>
  <version>0.3.0</version>
</dependency>
```

## Your first workbook

Each example writes a list of orders to `orders.xlsx`. Where the language supports object or record mapping, the sheet gets a styled, frozen header row and an auto filter automatically.

### .NET

```csharp
using Hypaxel;

await using var writer = XlsxWriter.Create("orders.xlsx");
await writer.WriteWorksheetAsync("Orders", orders);
await writer.CompleteAsync();
```

### Rust

```rust
let file = std::io::BufWriter::new(std::fs::File::create("orders.xlsx")?);
let mut writer = XlsxWriter::new(file);
writer.write_sheet_records("Orders", &orders)?;   // any T: Serialize
writer.finish()?;
```

### Python

```python
import hypaxel

hypaxel.to_xlsx(orders, "orders.xlsx")    # list of dicts / dataclasses / models, or a DataFrame
```

### Node.js

```ts
import { writeFile } from 'hypaxel'

await writeFile('orders.xlsx', orders)
```

### Browser

The same package runs in browsers on WebAssembly; bundlers pick that build automatically.

```ts
import { toBlob } from 'hypaxel'

const blob = await toBlob(orders, { sheetName: 'Orders' })
const link = Object.assign(document.createElement('a'), { href: URL.createObjectURL(blob), download: 'orders.xlsx' })
link.click()
URL.revokeObjectURL(link.href)
```

See [Browsers](https://hypaxel.libs.vensas.de/docs/nodejs#browsers) for loading the WebAssembly module and streaming large exports.

### Go

```go
w := hypaxel.NewWriter(file)
if err := hypaxel.WriteSheet(w, "Orders", orders); err != nil {
	return err
}
return w.Close()
```

### Java

```java
try (XlsxWriter writer = XlsxWriter.create(Path.of("orders.xlsx"))) {
    writer.writeWorksheet("Orders", Order.class, orders);
}
```

### PHP

```php
use Vensas\Hypaxel\Xlsx;

Xlsx::writeFile('orders.xlsx', $orders);
```

## Streaming a web response

The main use case is an export endpoint that streams the workbook while rows are read from the database. The client starts receiving bytes immediately, and memory per request stays bounded.

### ASP.NET Core

```csharp
app.MapGet("/orders.xlsx", (AppDb db) =>
    Results.Extensions.Excel(db.Orders.AsNoTracking().AsAsyncEnumerable(), "orders"));
```

### axum

```rust
async fn orders(State(pool): State<PgPool>) -> Xlsx {
    Xlsx::from_stream("Orders", sqlx::query_as::<_, Order>("SELECT ...").fetch(&pool)).filename("orders.xlsx")
}
```

### FastAPI

```python
from hypaxel.starlette import XlsxResponse

@app.get("/orders.xlsx")
async def orders():
    return XlsxResponse(hypaxel.astream_records(fetch_orders()), filename="orders.xlsx")
```

### Express

```ts
import { CONTENT_TYPE, stream } from 'hypaxel'
import { pipeline } from 'node:stream/promises'

app.get('/orders.xlsx', async (req, res) => {
  res.setHeader('Content-Type', CONTENT_TYPE)
  res.setHeader('Content-Disposition', 'attachment; filename="orders.xlsx"')
  await pipeline(stream(db.orders.cursor()), res)
})
```

### Go net/http

```go
http.Handle("/orders.xlsx", hypaxelhttp.Handler("orders", func(r *http.Request, w *hypaxel.Writer) error {
	return hypaxel.WriteSheetSeq2(w, "Orders", db.Orders(r.Context()))
}))
```

### Spring MVC

```java
StreamingResponseBody body = out -> {
    try (XlsxWriter writer = XlsxWriter.create(out); Stream<Order> orders = repository.streamAll()) {
        writer.writeWorksheet("Orders", Order.class, orders);
    }
};
```

### PHP

```php
Xlsx::download('orders.xlsx', $pdo->query('SELECT id, customer, amount FROM orders', PDO::FETCH_ASSOC));
```

## Reading a workbook

The readers in .NET, Rust, Python, Go and Java return rows one at a time, with memory bounded by the shared strings plus one row. Dates, times and durations are recognised from number formats. Node.js and PHP do not read yet.

### .NET

```csharp
using var reader = XlsxReader.Open("orders.xlsx");
using var rows = reader.OpenWorksheet("Orders");
while (rows.Read())
{
    var row = rows.Row;
    if (row.TryGetString(1, out var customer) && row.TryGetDouble(3, out var amount))
        Console.WriteLine($"{row.Number}: {customer} {amount}");
}
```

### Rust

```rust
let mut reader = hypaxel::XlsxReader::open("orders.xlsx")?;
let mut rows = reader.worksheet("Orders")?;
while let Some(row) = rows.next_row()? {
    let amount = row.get(3).as_f64();
}
```

### Python

```python
for row in hypaxel.iter_rows("orders.xlsx", "Orders"):
    print(row)

df = hypaxel.read_dataframe("orders.xlsx")    # pandas; library="polars" for polars
```

### Go

```go
r, err := hypaxel.OpenReader("orders.xlsx")
if err != nil {
	return err
}
defer r.Close()
rows, err := r.Rows("Orders")
if err != nil {
	return err
}
defer rows.Close()
for rows.Next() {
	amount := rows.Row().Get(3)
	_ = amount
}
return rows.Err()
```

### Java

```java
try (XlsxReader reader = XlsxReader.open(Path.of("orders.xlsx"));
     SheetReader rows = reader.worksheet("Orders")) {
    for (Row row = rows.nextRow(); row != null; row = rows.nextRow()) {
        System.out.println(row.getString(1) + " " + row.getNumber(3));
    }
}
```

Columns are 1-based in every reader, and rows without values are skipped. Each language guide covers values, errors and limits for untrusted input: [.NET](https://hypaxel.libs.vensas.de/docs/dotnet#reading), [Rust](https://hypaxel.libs.vensas.de/docs/rust#reading), [Python](https://hypaxel.libs.vensas.de/docs/python#reading), [Go](https://hypaxel.libs.vensas.de/docs/go#reading), [Java](https://hypaxel.libs.vensas.de/docs/java#reading).

## Key constraints

When writing, Hypaxel never goes back to rewrite earlier parts of the file. That is what keeps memory constant, and it sets a few rules:

- **Write order.** Rows are written top to bottom and cells left to right. To leave gaps, skip cells or rows, or begin a row at a later row number.
- **One sheet at a time.** Adding a worksheet completes the previous one. You cannot return to an earlier sheet.
- **Sheet options up front.** Column definitions, frozen panes and the row outline depth go into the worksheet options when you create the sheet, because they come before the cell data in the file. Merged cells, auto filters and tables can be added at any time before the sheet completes. Auto-fit columns are the exception that measures data first: the sheet's output is held back for a sample of rows.
- **Formulas without cached results.** Formulas are stored without a computed value. Excel recalculates them when the file opens.

> **Tip:**
>
> Read [Troubleshooting](https://hypaxel.libs.vensas.de/docs/troubleshooting) for the details behind these rules, including Excel's size limits, dates and time zones, and readers that need cell references on every cell.
