---
id: numbers-parser
version: "4.19.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# numbers-parser — Read and write Apple Numbers spreadsheets

License: permissive · Maintenance: active · Downloads: 1.3M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.3M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

apple numbers file parser, read numbers spreadsheets python, edit .numbers files programmatically, numbers spreadsheet library, convert numbers to dataframe, apple numbers automation, spreadsheet-parsing, apple-numbers, data-extraction

[View on SkillFed](https://skillfed.io/packages/numbers-parser) · [View on PyPI](https://pypi.org/project/numbers-parser/)