Large Excel files

Workbooks with millions of cells, without the heap blowing up.

Install#

dart pub add excel_plus

import 'package:excel_plus/excel_plus.dart';

Why big spreadsheets break things#

The obvious way to parse a spreadsheet is to load the XML for a sheet into a document tree and walk it. That tree is many times larger than the file, so a workbook of a few hundred megabytes can need tens of gigabytes of memory. Most out of memory crashes when reading a spreadsheet come from this, not from the file itself.

excel_plus reads cell data as a stream of events instead of building that tree, and only parses a sheet the first time you touch it.

Streaming a file from disk#

On the VM, desktop or mobile, decodeBuffer reads the file lazily rather than pulling all of it into memory first.

final excel = Excel.decodeBuffer(InputFileStream('input.xlsx'));

InputFileStream is re-exported, so there is no separate import to add. It reads a path, so it is native only, and it holds the file open while the workbook is in use. Use decodeBytes for bytes from a network response, an asset, or in the browser.

Only touch the sheets you need#

Sheets are parsed on first access. Reading one sheet out of a workbook of thirty does not pay for the other twenty nine, so avoid iterating tables.keys when you only want one.

final excel = Excel.decodeBuffer(InputFileStream('big.xlsx'));

// Only this sheet is parsed.
final sheet = excel['Q4'];

Streaming the output#

Writing has the same problem in reverse. encodeToStream pushes the file to a sink as it is produced, so the whole workbook is never held as one buffer.

final sink = File('big.xlsx').openWrite();
excel.encodeToStream(sink.add);
await sink.close();

Keeping an interface responsive#

Encoding a large workbook is CPU bound and will block whatever thread it runs on. In an app, push it to a background isolate.

final bytes = await excel.encodeAsync();

On the web this falls back to the main thread, since isolates are not available there.

Untouched parts are not re-encoded#

When a workbook is opened and saved, the parts you did not modify are carried across as they were rather than being rebuilt. That keeps saves fast on large files and avoids losing anything the library does not model.