Skip to content
Docs: Hypaxel for GoMenu

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.

Compatibilityv0.3.0 unreleased
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#

Install · Go modules
go get github.com/vensas/hypaxel/go

Not 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/go

Quick 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"`
ElementMeaning
first elementColumn header. Empty means the field name
width=NColumn width in characters, up to 255
hiddenHide the column
dateWrite a time.Time as a date without time of day
format=CODEExcel 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.

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

MethodReturns
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:

ErrorCause
ErrInvalidFileNot a ZIP archive; a legacy .xls or password-protected workbook (OLE file); a Word or PowerPoint file
ErrSheetNotFoundNo sheet with that name or index
ErrMalformedInvalid XML, a bad cell value or reference, a missing part, or a ZIP entry that fails its size or CRC check
ErrLimitExceededOne of the safety limits above was reached
ErrUnsupportedA chart sheet, a UTF-16 part, an encrypted ZIP entry or an unknown compression method

Options#

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

OptionDefaultMeaning
WithCompressionLevel(n)1Deflate level 0-9. 0 stores without compressing
WithSharedStrings(true)offShared string table: can be smaller for repeated text, uses more memory
WithFlushThreshold(n)65536Compressed bytes buffered before they are written to the destination
WithDate1904(true)offUse the 1904 date system
WithCellReferences(true)offWrite 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 rowsApple M1 Max, 10 cores, macOS 26.6; Go 1.27.4. Compared with excelize 2.11.1.
100k rowslower is better
  1. Hypaxel, typed cells88 ms, best
  2. Hypaxel, struct mapping95 ms, 1.1×
  3. Hypaxel, WriteRow100 ms, 1.1×
  4. Hypaxel, shared strings113 ms, 1.3×
  5. excelize, StreamWriter432 ms, 4.9×
  6. excelize, in-memory1,740 ms, 20×
Go: 100,000 and 1,000,000 rows
Case100k rowsAllocated (100k)Peak RSS (100k)1M rowsAllocated (1M)Peak RSS (1M)
Hypaxel, typed cells88 ms0.2 MB18 MB0.92 s0.4 MB19 MB
Hypaxel, struct mapping95 ms0.2 MB18 MB0.97 s0.4 MB19 MB
Hypaxel, WriteRow100 ms10.9 MB19 MB1.02 s107 MB20 MB
Hypaxel, shared strings113 ms17.7 MB28 MB1.37 s214 MB157 MB
excelize, StreamWriter432 ms171 MB78 MB5.62 s1,317 MB179 MB
excelize, in-memory1,740 ms1,250 MB631 MBnot runnot runnot run

Methodology and notes · Benchmark source

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 rowsApple 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.
Inline stringslower is better
  1. Hypaxel, Rows.Next1.16 s, best
  2. Hypaxel, Rows.All1.16 s, best
  3. excelize, Rows with RawCellValue15.55 s, 13×
  4. excelize, Rows (formatted values)68.33 s, 59×
  5. xlsxreader, ReadRows14.51 s, 13×
Go: reading 1,000,000 rows
CaseInline stringsPeak RSS (inline)Shared stringsPeak RSS (shared)
Hypaxel, Rows.Next1.16 s21 MB1.2 s73 MB
Hypaxel, Rows.All1.16 s21 MB1.21 s86 MB
excelize, Rows with RawCellValue15.55 s22 MB17 s142 MB
excelize, Rows (formatted values)68.33 s23 MB69.41 s142 MB
xlsxreader, ReadRows14.51 s22 MB12.86 s163 MB
tealeg/xlsx, OpenFilenot runnot runnot runnot run

Methodology and notes · Benchmark source

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