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.
v0.3.0 unreleasedLast updated View as Markdown
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#
go get github.com/vensas/hypaxel/goNot published yetgithub.com/vensas/hypaxel/go is not on Go modules yet. The command above is what installation will look like once it is.
The module is not published yet. Until then, build it from source: see Building from source. It requires Go 1.26 or later. The package name is hypaxel:
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:
require github.com/vensas/hypaxel/go v0.0.0
replace github.com/vensas/hypaxel/go => /path/to/hypaxel/goQuick start#
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:
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#
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:
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#
`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#
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:
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.
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:
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:
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:
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:
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 whichTime()returns false). A time of day without a date falls on 1899-12-31 (1904-01-01 in the 1904 system); use itsClock().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
GOMAXPROCSis 1, andWithConcurrentInflate(false)turns it off for batch jobs that already keep every core busy. Callrows.Close()when you stop reading early; a range loop overrows.All()does that for you. - Concurrency: a
Readeris safe for concurrent use: open several sheets, or the same sheet twice, from different goroutines. EachRowsbelongs 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/xlsxreaderandtealeg/xlsxread such files wrongly or fail. UseWithCellReferences(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.Timeis written as the wall-clock time of its location; convert witht.UTC()ort.In(loc)first if you need another one. The zerotime.Timeis 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.
NaNand 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
Writeris not safe for concurrent use. Separate writers are independent. WriteRowallocates: passing values asanyboxes 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.
- Hypaxel, typed cells88 ms, best
- Hypaxel, struct mapping95 ms, 1.1×
- Hypaxel, WriteRow100 ms, 1.1×
- Hypaxel, shared strings113 ms, 1.3×
- excelize, StreamWriter432 ms, 4.9×
- excelize, in-memory1,740 ms, 20×
| 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 |
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.
- Hypaxel, Rows.Next1.16 s, best
- Hypaxel, Rows.All1.16 s, best
- excelize, Rows with RawCellValue15.55 s, 13×
- excelize, Rows (formatted values)68.33 s, 59×
- xlsxreader, ReadRows14.51 s, 13×
| 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 |
See Performance for methodology and reproduction, and Benchmarks for the full tables.
Building from source#
The source is at github.com/vensas/hypaxel, in the go/ directory. Report bugs at 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/.
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