# Hypaxel for Go

> A Go Excel writer and reader with no dependencies: stream XLSX files to any io.Writer or http.ResponseWriter, and read large workbooks one row at a time.

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

Hypaxel for Go is an Excel writer for services that export large tables from Go. It writes `.xlsx` files as a forward-only stream: each cell is serialized to XML the moment you write it and deflated into a small buffer that is flushed to your `io.Writer`. Memory stays flat whether you export 10 rows or a million, the typed cell methods allocate nothing per cell or per row, and a download can start while your query is still running. It also reads `.xlsx` files as a stream, one row at a time, with memory bounded by the shared string table plus one row, about 13 times faster than excelize's `Rows` iterator. It is pure Go, uses only the standard library, needs no cgo, and returns errors instead of panicking on bad input.

| | |
| --- | --- |
| Package | `github.com/vensas/hypaxel/go` |
| Requires | Go 1.26+ |
| Engine | Native Go, standard library only; writer and streaming reader |
| Web | hypaxelhttp.Handler, hypaxelhttp.Serve |
| Registry | Go modules (not published yet) |
| License | Apache-2.0 |

## Install

```bash
go get github.com/vensas/hypaxel/go
```

_Status: not published to Go modules yet._

The module is not published yet. Until then, build it from source: see [Building from source](#building-from-source). It requires Go 1.26 or later. The package name is `hypaxel`:

```go
import hypaxel "github.com/vensas/hypaxel/go"
```

Until the module is published, use a local copy of the repository from another module with a replace directive:

```text
require github.com/vensas/hypaxel/go v0.0.0
replace github.com/vensas/hypaxel/go => /path/to/hypaxel/go
```

## Quick start

```go
type Order struct {
	ID       int       `xlsx:"Order #,width=10"`
	Customer string    `xlsx:"Customer,width=30"`
	Created  time.Time `xlsx:"Created,date"`
	Amount   float64   `xlsx:"Amount,width=14,format=#,##0.00"`
	Internal string    `xlsx:"-"`
}

func export(path string, orders []Order) error {
	file, err := os.Create(path)
	if err != nil {
		return err
	}
	defer file.Close()

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

Structs get a bold, frozen header row, the tagged column widths and an auto filter. Slices are written as plain rows:

```go
err := hypaxel.WriteSheet(w, "Matrix", [][]any{{1, "a"}, {2, "b"}})
```

`WriteSheetSeq` takes an `iter.Seq[T]`, `WriteSheetSeq2` an `iter.Seq2[T, error]` and stops at the first error, and `WriteSheetChan` reads from a channel until it is closed or the context is done. All of them consume their source lazily.

## Streaming HTTP responses

```go
import (
	hypaxel "github.com/vensas/hypaxel/go"
	"github.com/vensas/hypaxel/go/hypaxelhttp"
)

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

`Handler` sets `Content-Type` and `Content-Disposition`, flushes every chunk to the client, and stops the export when the request context is cancelled. If the export fails before anything was sent, the client gets a 500; if it fails later, the connection is aborted with `http.ErrAbortHandler` so the browser reports a failed download instead of saving a truncated file.

`Serve` does the same inside your own handler and returns the error, which wraps `hypaxelhttp.ErrPartial` when part of the workbook had already been sent:

```go
func export(rw http.ResponseWriter, r *http.Request) {
	err := hypaxelhttp.Serve(rw, r, "report.xlsx", func(w *hypaxel.Writer) error {
		sheet, err := w.AddSheet("Report")
		if err != nil {
			return err
		}
		return sheet.WriteRow("Generated", time.Now())
	})
	if err != nil && !errors.Is(err, hypaxelhttp.ErrPartial) {
		http.Error(rw, "export failed", http.StatusInternalServerError)
	}
}
```

Any other framework works the same way: pass its response writer to `hypaxel.NewWriter`.

## Struct mapping

```go
`xlsx:"Header,width=20,hidden,date,format=#,##0.00"`
```

| Element | Meaning |
| --- | --- |
| first element | Column header. Empty means the field name |
| `width=N` | Column width in characters, up to 255 |
| `hidden` | Hide the column |
| `date` | Write a `time.Time` as a date without time of day |
| `format=CODE` | Excel number format. Must come last: it takes the rest of the tag, because format codes contain commas |
| `-` | Skip the field |

Fields map to columns in declaration order. Embedded structs are flattened, unexported fields are skipped, and a header cannot contain a comma.

`Write`, `WriteRow` and struct fields accept strings, all integer and float types, `bool`, `time.Time`, `time.Duration`, `[]byte` (as text), `Formula`, `Cell`, `nil`, pointers to these (a nil pointer is an empty cell) and named types based on them. Types implementing `driver.Valuer` (such as `sql.NullString`), `encoding.TextMarshaler` or `fmt.Stringer` are written through those methods.

## Full control with `Writer`

```go
w := hypaxel.NewWriter(dst)
header := w.AddStyle(hypaxel.Style{
	Font:      hypaxel.Font{Bold: true, Color: hypaxel.White},
	Fill:      hypaxel.RGB(0x30, 0x54, 0x96),
	Alignment: hypaxel.Alignment{Horizontal: hypaxel.AlignCenter},
})
money := w.AddStyle(hypaxel.Style{NumberFormat: hypaxel.FormatThousands2})

sheet, err := w.AddSheetOptions("Sales", hypaxel.SheetOptions{
	FrozenRows: 1,
	Columns:    hypaxel.Widths(20, 12, 14),
})
if err != nil {
	return err
}
sheet.WriteStrings([]string{"Product", "Date", "Revenue"}, header)
sheet.WriteRow("Widget", time.Date(2024, 5, 1, 0, 0, 0, 0, time.UTC), hypaxel.Styled(1234.5, money))
sheet.WriteRow("Gadget", time.Date(2024, 5, 2, 0, 0, 0, 0, time.UTC), hypaxel.Styled(99.99, money))
sheet.WriteRow("Total", nil, hypaxel.Styled(hypaxel.Formula("SUM(C2:C3)"), money))
return w.Close()
```

For the hottest loops, write cells one at a time. Nothing is boxed and nothing is allocated:

```go
for _, o := range orders {
	sheet.WriteInt(int64(o.ID))
	sheet.WriteString(o.Customer)
	sheet.WriteFloat(o.Total, money)
	sheet.WriteTime(o.CreatedAt)
	if err := sheet.EndRow(); err != nil {
		return err
	}
}
```

Worksheets are written one at a time: adding a worksheet completes the previous one. The full method tables for `Writer`, `Sheet`, package functions and style types are in the [API reference](https://hypaxel.libs.vensas.de/docs/api#go).

## Tables, row grouping and auto-fit

### Grouped rows

Give rows an outline level to make them collapsible. The deepest level is declared when the worksheet is added, because Excel reads it before the rows:

```go
sheet, _ := w.AddSheetOptions("Regions", hypaxel.SheetOptions{RowOutlineLevels: 2, OutlineSummaryAbove: true})
sheet.WriteRow("North", 300)
sheet.BeginRow(hypaxel.RowOptions{OutlineLevel: 1})
sheet.WriteRow("Store A", 120)
sheet.BeginRow(hypaxel.RowOptions{OutlineLevel: 2, Hidden: true})
sheet.WriteRow("Till 1", 60)
```

A row begun with `BeginRow` is filled by the next whole-row write (`WriteRow`, `WriteStrings`, `WriteStruct`, ...) as long as it has no cells yet. `Hidden` and `Collapsed` mark the rows of a collapsed group and its summary row. `OutlineSummaryAbove` puts the expand button above the group.

### Excel tables

`AddTable` turns a range into a named, styled table with filter buttons. With a header row (the default), `Columns` must repeat the header texts exactly:

```go
sheet.WriteRow("Product", "Units")
sheet.WriteRow("Widget", 3)
sheet.WriteRow("Gadget", 5)
err := sheet.AddTable(hypaxel.Table{
	FirstRow: 1, FirstColumn: 1, LastRow: sheet.Row(), LastColumn: 2,
	Name:    "Orders",
	Columns: []string{"Product", "Units"},
	Style:   hypaxel.TableStyleMedium(9),
})
```

The range may include rows not written yet. Names are unique in the workbook and follow Excel's name rules; an empty `Name` gives `Table1`, `Table2`, ... `Style` defaults to Medium 2; `TableStyleNone` and `TableStyleLight(n)`, `TableStyleMedium(n)`, `TableStyleDark(n)` select the others. `NoHeaderRow`, `NoFilterButtons`, `NoRowStripes`, `ColumnStripes`, `HighlightFirstColumn` and `HighlightLastColumn` adjust the rest. Tables cannot overlap each other, merged cells or the worksheet's `AutoFilter`.

### Auto-fit columns

`AutoFit` sizes columns without an explicit width to their content:

```go
sheet, _ := w.AddSheetOptions("Report", hypaxel.SheetOptions{
	AutoFit: &hypaxel.AutoFit{},          // measure the first 1,000 rows, widths up to 255
	Columns: []hypaxel.Column{{Width: 12}}, // explicit widths win
})
```

Column widths come before the cells in the file, so the worksheet's XML is held back until `SampleRows` rows are written (default 1,000), 8 MiB of XML is reached or the sheet ends. Then the widths are fixed and streaming continues as usual; memory is bounded by the sample. Widths are estimated from the text, number format, font size and boldness of each cell. Formulas, blank cells and rows after the sample are not measured. `MaxWidth` caps a fitted width.

## Reading

`OpenReader` opens a workbook by path, `NewReader` takes any `io.ReaderAt` and its size. Rows are streamed one at a time:

```go
r, err := hypaxel.OpenReader("orders.xlsx")   // or hypaxel.NewReader(readerAt, size)
if err != nil {
	return err
}
defer r.Close()
fmt.Println(r.SheetNames())

rows, err := r.Rows("Orders")                  // or r.RowsAt(0)
if err != nil {
	return err
}
defer rows.Close()
for rows.Next() {
	row := rows.Row()                          // reused by the next call to Next
	// row.Index() is the 1-based Excel row; rows without values are skipped.
	for column, v := range row.Cells() {
		switch v.Kind() {
		case hypaxel.ValueString:
			fmt.Println(hypaxel.CellRef(row.Index(), column), v.Text())
		case hypaxel.ValueNumber:
			n, _ := v.Float()
			fmt.Println(n)
		case hypaxel.ValueDateTime:
			t, _ := v.Time()                   // or v.Duration() for [h]:mm:ss formats
			fmt.Println(t)
		case hypaxel.ValueBool:
			b, _ := v.Bool()
			fmt.Println(b)
		case hypaxel.ValueError:
			fmt.Println("error", v.Text())    // #N/A, #DIV/0!, ...
		}
	}
	amount := row.Get(3)                       // by 1-based column; empty Value if missing
	dense := row.AppendValues(nil)             // columns 1..LastColumn, empty Values for gaps
	_, _ = amount, dense
}
return rows.Err()
```

`rows.All()` returns an `iter.Seq2[*Row, error]` for `for row, err := range rows.All()`; the loop closes the rows when it ends. `Row` also has `Len`, `LastColumn` and `Cell(i)` for index loops.

| Function | Purpose |
| --- | --- |
| `OpenReader(path, opts...)`, `NewReader(src io.ReaderAt, size, opts...)` | Open a workbook; `Close` closes a file opened by path |
| `Sheets()`, `SheetNames()` | Sheets in workbook order with `Name`, `Visibility` (`SheetVisible`, `SheetHidden`, `SheetVeryHidden`) and `Kind` (`SheetKindWorksheet`, `SheetKindChartsheet`, `SheetKindOther`) |
| `Rows(name)`, `RowsAt(index)` | Stream a sheet, by name (exact, then case-insensitive) or 0-based index |
| `Date1904()` | Whether the workbook uses the 1904 date system |
| `WithMaxSharedStringsBytes(n)` | Option: cap the shared string table (default 1 GiB) |
| `WithConcurrentInflate(on)` | Option: decompress on a separate goroutine while parsing (default on, off when `GOMAXPROCS` is 1) |

### Values

A `Value` is a small immutable struct; the zero value is empty.

| Method | Returns |
| --- | --- |
| `Kind()` | `ValueEmpty`, `ValueString`, `ValueNumber`, `ValueBool`, `ValueDateTime` or `ValueError` |
| `Text()` | The text of a string or error value |
| `Float()` | A number, or the serial number of a date |
| `Bool()` | A boolean |
| `Time()` | A date value as a UTC `time.Time` (the wall clock Excel shows), rounded to the millisecond |
| `Duration()` | A date value as elapsed time, as `[h]:mm:ss` formats show it |
| `DateKind()` | What the number format shows: `DateKindDate`, `DateKindDateTime`, `DateKindTime`, `DateKindDuration` |
| `String()` | The value as text, like Excel's General format, with dates in ISO 8601 |

- **Dates:** Excel stores dates as numbers. A number whose built-in or custom number format shows a date, time or duration becomes a `ValueDateTime`; `Float()` still gives the serial. Both date systems are supported, including Excel's fictitious 1900-02-29 (serial 60, for which `Time()` returns false). A time of day without a date falls on 1899-12-31 (1904-01-01 in the 1904 system); use its `Clock()`. `t="d"` cells with ISO 8601 text are read as dates too.
- **Formulas:** the cached result is returned; a formula that was never calculated has no value.
- **Memory:** rows are decompressed and parsed as a stream. What stays in memory is the shared string table (text that Excel stores once per workbook, loaded when the first sheet is opened) plus the current row. Values never point into reused buffers: strings stay valid after the row is replaced.
- **Concurrent inflate:** by default each sheet and the shared string table are decompressed on a goroutine of their own, up to 256 KiB ahead of the parser, which roughly halves the time to read a sheet when a CPU core is free. It costs about 4% more CPU time in total, is off when `GOMAXPROCS` is 1, and `WithConcurrentInflate(false)` turns it off for batch jobs that already keep every core busy. Call `rows.Close()` when you stop reading early; a range loop over `rows.All()` does that for you.
- **Concurrency:** a `Reader` is safe for concurrent use: open several sheets, or the same sheet twice, from different goroutines. Each `Rows` belongs to one goroutine.
- **Compatibility:** files from Excel, LibreOffice, excelize, openpyxl and other producers: package relationships instead of fixed paths, Strict Open XML, prefixed namespaces, cells and rows without references, out-of-order cells, rich text, inline strings, phonetic runs, CDATA, and Excel's `_xHHHH_` escapes.

Not read yet: formula text, styles beyond date detection, merged ranges, comments and hyperlinks.

### Untrusted input

The reader is built for uploads. Document type declarations are rejected (no entity expansion), every XML token is limited to 16 MiB and every row to 16,384 cells and 256 MiB of text, ZIP entries must match their declared size and CRC-32, and `WithMaxSharedStringsBytes` caps the shared string table. Damaged input returns an error, never a panic or a hang; the reader is fuzz-tested.

### Read errors

Errors name the part they come from, as `*ReadError` with a `Part` field. Test for the cause with `errors.Is`:

| Error | Cause |
| --- | --- |
| `ErrInvalidFile` | Not a ZIP archive; a legacy `.xls` or password-protected workbook (OLE file); a Word or PowerPoint file |
| `ErrSheetNotFound` | No sheet with that name or index |
| `ErrMalformed` | Invalid XML, a bad cell value or reference, a missing part, or a ZIP entry that fails its size or CRC check |
| `ErrLimitExceeded` | One of the safety limits above was reached |
| `ErrUnsupported` | A chart sheet, a UTF-16 part, an encrypted ZIP entry or an unknown compression method |

## Options

Writer options are passed to `NewWriter(dst, opts...)`:

| Option | Default | Meaning |
| --- | --- | --- |
| `WithCompressionLevel(n)` | `1` | Deflate level 0-9. 0 stores without compressing |
| `WithSharedStrings(true)` | off | Shared string table: can be smaller for repeated text, uses more memory |
| `WithFlushThreshold(n)` | `65536` | Compressed bytes buffered before they are written to the destination |
| `WithDate1904(true)` | off | Use the 1904 date system |
| `WithCellReferences(true)` | off | Write a reference such as `B7` on every cell |

## Write errors

Functions that validate their arguments (`AddSheet`, `BeginRow`, `MergeCells`, `AutoFilter`, `AddTable`) return the error and leave the workbook usable. The cell methods return nothing, so that hot loops stay cheap: a failed cell write or a failed write to the destination is recorded, and every later call (`EndRow`, `WriteRow`, `Close`, ...) returns it. After such an error the output is incomplete and must be discarded.

Test for causes with `errors.Is`: `ErrInvalidSheetName`, `ErrDuplicateSheetName`, `ErrRowOrder`, `ErrRowOutOfRange`, `ErrTooManyColumns`, `ErrTextTooLong`, `ErrInvalidStyle`, `ErrInvalidArgument`, `ErrInvalidTableName`, `ErrDuplicateTableName`, `ErrOverlappingRange`, `ErrNoVisibleSheet`, `ErrUnsupported`, `ErrSheetClosed`, `ErrClosed`. Errors from the destination are returned unchanged.

## Notes and limits

- **Write order:** rows are written top to bottom, and one worksheet at a time. Column widths (unless auto-fitted), frozen panes and the outline depth are set when the worksheet is added.
- **Excel limits apply:** 1,048,576 rows, 16,384 columns and 32,767 characters per cell, 31 characters per worksheet name.
- **Readers that need cell references:** by default Hypaxel omits cell references that follow from a cell's position. That is valid and is read by Excel, LibreOffice, excelize, openpyxl, calamine and Hypaxel's own reader, but ExcelJS, `thedatashed/xlsxreader` and `tealeg/xlsx` read such files wrongly or fail. Use `WithCellReferences(true)` for those.
- **Colors in excelize:** Hypaxel writes no theme part. excelize 2.11 returns empty fill and border colors for such workbooks when reading styles back; the colors are in the file and other readers show them.
- **Dates:** Excel has no time zones, so a `time.Time` is written as the wall-clock time of its location; convert with `t.UTC()` or `t.In(loc)` first if you need another one. The zero `time.Time` is an empty cell. Dates Excel cannot represent (before 1900, or before 1904 in the 1904 system) are written as ISO 8601 text.
- **Numbers:** Excel stores every number as a float64, so integers beyond ±2^53 lose precision. `NaN` and infinities are written as `#NUM!`.
- **Text:** invalid UTF-8 is replaced with U+FFFD, and control characters are written with Excel's `_xHHHH_` escape.
- **Formulas** are stored without cached results; Excel recalculates them when the file opens.
- **Styles** belong to the writer that created them.
- **Concurrency:** a `Writer` is not safe for concurrent use. Separate writers are independent.
- **`WriteRow` allocates:** passing values as `any` boxes them, which costs about one small allocation per cell. The typed methods and struct mapping do not.

## Performance

On an Apple M1 Max, Hypaxel writes 100,000 rows × 10 columns in about 0.09 s and 1 million rows in about 0.9 s with typed cells, about 5 to 6 times faster than excelize's `StreamWriter` and 20 times faster than excelize's in-memory API. The typed and struct-mapping paths make a few dozen allocations per workbook regardless of row count, and a million-row export peaks at the same resident memory as a 100k-row one.

**Go: 100,000 and 1,000,000 rows**

| Case | 100k rows | Allocated (100k) | Peak RSS (100k) | 1M rows | Allocated (1M) | Peak RSS (1M) |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| **Hypaxel, typed cells** | 88 ms | 0.2 MB | 18 MB | 0.92 s | 0.4 MB | 19 MB |
| **Hypaxel, struct mapping** | 95 ms | 0.2 MB | 18 MB | 0.97 s | 0.4 MB | 19 MB |
| **Hypaxel, WriteRow** | 100 ms | 10.9 MB | 19 MB | 1.02 s | 107 MB | 20 MB |
| **Hypaxel, shared strings** | 113 ms | 17.7 MB | 28 MB | 1.37 s | 214 MB | 157 MB |
| excelize, StreamWriter | 432 ms | 171 MB | 78 MB | 5.62 s | 1,317 MB | 179 MB |
| excelize, in-memory | 1,740 ms | 1,250 MB | 631 MB | not run | not run | not run |

_Apple M1 Max, 10 cores, macOS 26.6; Go 1.27.4. Compared with excelize 2.11.1. Time and allocated bytes from go test -bench with the rows built beforehand and a discarding destination: about a dozen iterations per case at 100k rows (one for the in-memory case), three at 1M. Peak RSS from separate runs, one process per case, generating the rows on the fly; it includes the Go runtime and both libraries. Other processes were using the machine, so treat small differences as noise. Source: https://github.com/vensas/hypaxel/tree/main/go/tests_

### Reading performance

Reading 1 million rows of the same workload, written with a cell reference on every cell as Excel writes them, takes about 1.2 s with inline or shared strings, about 11 to 14 times faster than excelize's `Rows` iterator and xlsxreader. With inline strings the reader peaks at 21 MB. These files are about 40% larger than the ones in the other languages' read benchmarks, so compare Hypaxel with the Go readers in the same table, not with other languages.

**Go: reading 1,000,000 rows**

| Case | Inline strings | Peak RSS (inline) | Shared strings | Peak RSS (shared) |
| --- | ---: | ---: | ---: | ---: |
| **Hypaxel, Rows.Next** | 1.16 s | 21 MB | 1.2 s | 73 MB |
| **Hypaxel, Rows.All** | 1.16 s | 21 MB | 1.21 s | 86 MB |
| excelize, Rows with RawCellValue | 15.55 s | 22 MB | 17 s | 142 MB |
| excelize, Rows (formatted values) | 68.33 s | 23 MB | 69.41 s | 142 MB |
| xlsxreader, ReadRows | 14.51 s | 22 MB | 12.86 s | 163 MB |
| tealeg/xlsx, OpenFile | not run | not run | not run | not run |

_Apple M1 Max, 10 cores, macOS 26.6; Go 1.27.4. Compared with excelize 2.11.1, thedatashed/xlsxreader 1.2.8, tealeg/xlsx 3.3.13. Each reader runs in its own process, best of three, on an otherwise idle machine. Every reader must return the same checksum (rows, cells, sum of numbers, dates as Unix seconds, string bytes, TRUE count), which the harness verifies. The inline-strings file is 70.7 MB, the shared-strings file 71.5 MB. Source: https://github.com/vensas/hypaxel/tree/main/go/tests_

See [Performance](https://hypaxel.libs.vensas.de/docs/performance) for methodology and reproduction, and [Benchmarks](https://hypaxel.libs.vensas.de/benchmarks) for the full tables.

## Building from source

The source is at [github.com/vensas/hypaxel](https://github.com/vensas/hypaxel), in the `go/` directory. Report bugs at [github.com/vensas/hypaxel/issues](https://github.com/vensas/hypaxel/issues).

It requires Go 1.26 or later. The library has no dependencies; the read-back tests and comparison benchmarks, which need excelize and the other readers compared above, live in a module of their own under `tests/`.

```bash
cd go
go test ./...                 # unit tests, standard library only
go vet ./... && gofmt -l .
go test -fuzz FuzzReader -fuzztime 1m    # or FuzzSheetXML
cd tests && go test ./...     # reads every feature back with excelize, compares the readers
```
