The Ruby Spreadsheet library reads the old binary XLS format and nothing newer

One format, stated plainly in the user notes

The Spreadsheet Library is designed to read and write Spreadsheet Documents. As of version 0.6.0, only Microsoft Excel compatible spreadsheets are supported.

The clearest statement of the scope comes not from the maintainers but from the notes from users. Tom's note says the library only supports XLS format, it does not support XLSX format. That is the single fact that decides whether this library is usable for a project, and it is worth reading before anything else.

The XLS format is the binary BIFF format that Excel used from the 97 era through 2003, and the repository carries the two specifications that describe it: the Excel97-2007 Binary File Format Specification and excelfileformat.pdf, both linked from the README. That the project keeps the format specifications in the repository is a sign of how the work is done, since the implementation is written against the specification rather than against a sample file.

There is also a note from Alfred about cell formats. The library doesn't recognize cell formats in Excel created documents, which results in Floats returned for any number. That is a specific and important limitation: a workbook written by Excel carries format information the library does not read, and the practical effect is that a cell the author formatted as currency or a date comes back as a float rather than as a typed value.

So the library can read the structure and the data of an XLS file, and it will not read the formatting. Anything that depends on the cell format being interpreted correctly is where it falls short.

A rewrite of two earlier libraries

Spreadsheet is a combination and a complete rewrite of the Spreadsheet::Excel Library by Daniel J. Berger and the ParseExcel Library by Hannes Wyss. It can read, write and modify Spreadsheet Documents.

The authors section makes the lineage concrete. The original code is Spreadsheet::Excel, copyright 2005 by Daniel J. Berger, and ParseExcel, copyright 2003 by Hannes Wyss. The new code is copyright 2010 by ywesee GmbH, with three named addresses.

The version 0.6.0 mentioned in the description is the point where the scope narrowed to Excel compatible documents only, and the roadmap lists Remove backward compatibility code among the planned items, which suggests the older file format support was dropped rather than deprecated.

What is in the what's new list is a reasonable summary of where the work went. Supported outline, meaning grouping, functions. Significantly improved memory-efficiency when reading large Excel files. Limited Spreadsheet modification support. And improved handling of String Encodings.

That list is a good guide to the library's shape. Reading is the strong suit, with the memory work aimed at large workbooks. Modification is explicitly limited. And the encoding work matters because Excel files carry text in a variety of encodings that predate Unicode in the sheet format itself.

The roadmap says what the library will not do yet

The On the Roadmap section is short and it is effectively a list of what a user is missing.

Improved Format support and Styles, and Document Modification for Formats and Styles. Formula Support, and Document Modification for Formulas. Write-Support for BIFF5. And Remove backward compatibility code.

Read that as a set of boundaries. The library can read a workbook and can modify some of it, but it does not write formulas, it does not write or preserve styles, and it does not write the older BIFF5 format. The one modification feature that is listed as supported, limited Spreadsheet modification support, is the honest word for a capability that works for some things and not others.

The format question is the one that matters for a real project. A workbook that a user will open in Excel and edit by hand is a document with styles, and a library that does not write styles produces output that looks wrong even when the data is right. A workflow where the library generates a workbook for someone to read, rather than to edit, is where that does not matter.

The formula gap is similar. A generated report with computed values is fine, and a generated workbook with live formulas that a user then edits is not.

Installing, building and running the tests

The install instructions are the conventional Ruby ones.

Using RubyGems:

sudo gem install spreadsheet

And the README adds a note that if you do not like RubyGems, the maintainer would like to know which installation solution you prefer so it can be included in the future.

To build the gem yourself, the command is gem build spreadsheet, and the gem package is built in the pkg directory.

The tests run through bundler:

bundle install
bundle exec ruby test/suite.rb

And linting uses the standardrb tooling, with bundle exec rake standard to check and bundle exec standardrb --fix to auto-fix issues. The repository has a .standard.yml file at the top level, which is the configuration for that linter, plus a Rakefile and a Gemfile.

The runtime requirements are stated in the description. Spreadsheet requires Ruby 2.6+ and is tested against Ruby 2.6 through 3.4, JRuby, and ruby-head. The ruby-head inclusion is a good sign, since it means the library is checked against the unreleased Ruby rather than only against stable versions.

The dependencies are few and all in the standard library or a small wrapper: ruby-ole, which is the OLE compound file reader that the XLS format is built on, logger, and bigdecimal, which is what a spreadsheet library needs for the numeric types.

The repository also carries a History.md, a Manifest.txt for the gem, a GUIDE.md with usage examples, a bin/ directory for the command line tools the gem ships, and a devenv.nix, devenv.yaml and devenv.lock for a Nix based development environment.

Where Spreadsheet is the wrong choice

The first limit is the format itself, and it is not a gap that will close. XLS is a legacy binary format that Microsoft stopped writing in the 2000s, and every new tool in the ecosystem produces XLSX. A project that is reading files today is usually reading XLSX, and this library will not open them. The README says so, and the notes from users say so again.

The second is that the library is old in a way that shows. The original code dates from 2003 and 2005 and the rewrite from 2010, so the codebase is a decade and a half old with a correspondingly long tail of decisions that were right for a different Ruby and a different world. The remove backward compatibility code item on the roadmap is the acknowledgement of that. The last push was on 2026-04-21, so it is still touched, but there are no GitHub releases, which means there is no version history to point at and the gem's own releases live on RubyGems.

The third is the format support gap in a workbook that came from Excel. The user note about cell formats not being recognized, and numbers coming back as floats, is the kind of defect that only shows up with real data. Any pipeline that relies on a date or a currency cell being typed correctly will hit it, and there is no workaround other than reading the raw value and applying the format yourself.

The fourth is the styles and formulas gap, which is the same point from the other direction. A library that writes a workbook without styles or formulas produces something a human will have to fix, and for a reporting pipeline that output is often the deliverable.

The fifth is the licensing arrangement. The library is distributed under the GPLv3, and the README points to spreadsheet.ch for non-GPLv3 commercial licensing. A company that wants to use it in a closed source product has to take a separate licence, and a project that only discovered the GPL after choosing the library has a problem.

Editorial conclusion

Spreadsheet suits a Ruby project that has to read legacy Excel 97 to 2003 binary files, particularly on a platform where nothing else is available, and it is the wrong tool for anything involving XLSX, since the README states plainly that the library only supports XLS format and does not support XLSX format. Before adopting it, check the format support for the specific cell types you need, because the notes from users report that cell formats created in Excel are not recognized and numbers come back as floats. Verify first that you can accept GPLv3 or a commercial licence, since the project offers non-GPLv3 commercial licensing separately.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Project website
4. README
5. zdavatz/spreadsheet on GitHub