numbers-parser

What it is and what it does

numbers-parser is a Python library for reading and writing Apple Numbers spreadsheet files. It parses .numbers files (a proprietary format used by Apple's Numbers application) into Python objects representing sheets, tables, and cells, allowing programmatic access to cell values, formatting, and styles. The library supports Numbers versions 3.x through 14.4 and is tested against current releases.

You can read cell data as native Python types (strings, floats, booleans, dates, durations), access cells by integer index or Excel-style notation (e.g., "B2"), modify cell values, create new sheets and tables, and save changes to a new file. It integrates with pandas by returning row data as lists suitable for DataFrame construction. The package handles cell styling (fonts, colors, alignment, backgrounds) and supports writing new Numbers documents from scratch.

Use it for:

• Automate data extraction from Numbers spreadsheets for analysis or reporting pipelines.
• Convert Numbers files to pandas DataFrames for data science workflows.
• Programmatically generate or modify Numbers spreadsheets as part of a larger application.
• Batch process multiple Numbers documents without opening the Numbers application.
• Integrate Numbers data into Python-based business logic or financial calculations.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Read, edit, and write Apple Numbers spreadsheet files (.numbers) from Python, with support for cells, rows, tables, sheets, and styling.

Yes, if you work with Apple Numbers files and need programmatic access. The library is actively maintained, has no known vulnerabilities, and carries a permissive MIT license. Install friction is low on macOS and Linux but requires manual setup of snappy compression libraries; Windows support is limited to ARM architecture only. Not suitable for Windows x86 users without workarounds.

Install

numbers-parser on PyPI

pip install numbers-parser

uv add numbers-parser

poetry add numbers-parser

Installing numbers-parser

Before you install

Low install friction on macOS and Linux with package managers; Windows support is limited to ARM architecture only. Requires python-snappy binary dependencies (snappy compression library), which the package will attempt to install automatically but may require manual system library setup depending on your platform.

License in practice

MIT license permits commercial and private use, modification, and distribution with minimal restrictions—suitable for most projects.

Quickstart

pip install numbers-parser

from numbers_parser import Document

doc = Document("mydoc.numbers")
sheets = doc.sheets
tables = sheets[0].tables
rows = tables[0].rows()
print(rows[0][0].value)

Requires Python 3.10 or later. python-snappy binary dependencies (snappy compression library) must be available; on macOS use Homebrew, on Linux use apt-get or equivalent, on Windows ARM only.

Verify before relying

• Extent of Numbers file format coverage beyond versions 3.x through 14.4 and Creator Studio 15.1.
• Performance characteristics when working with large Numbers documents.
• Stability guarantees for write operations on existing Numbers files.

Package facts

Evidence: numbers_parser-4.19.0-py3-none-any.whl

Tags

More Spreadsheet packages