Install & Compatibility
Where this runs
tested against v4.18.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 3.971s · 44.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.9s · import 0.733s · 45MB
45MB installed
● package 45MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Document
✓ from numbers_parser import Document
Sheet
✓ from numbers_parser import Document
doc = Document('file.numbers')
sheet = doc.sheets[0]
Accessed as a property of a Document object.
Table
✓ from numbers_parser import Document
doc = Document('file.numbers')
sheet = doc.sheets[0]
table = sheet.tables[0]
Accessed as a property of a Sheet object.
Reads an Apple Numbers document, lists its sheets, and prints the data from the first table of the first sheet. Replace 'example.numbers' with the path to your own Numbers file. For this code to run, you need to ensure an 'example.numbers' file exists in the same directory, containing at least one sheet and one table.
from numbers_parser import Document
# Create a dummy Numbers file for demonstration
# In a real scenario, you would have an existing .numbers file.
# For this quickstart, we'll simulate a file path.
# Make sure 'mydoc.numbers' exists or replace with a real path.
# If you don't have one, create a simple one in Apple Numbers and save it.
file_path = 'example.numbers'
# You might need to create a simple example.numbers file manually
# with at least one sheet and one table for this to run.
# For example, create a new Numbers spreadsheet, add some data to Sheet 1, Table 1, and save as example.numbers.
try:
doc = Document(file_path)
sheets = doc.sheets
print(f"Document has {len(sheets)} sheets.")
if sheets:
first_sheet = sheets[0]
print(f"First sheet name: {first_sheet.name}")
if first_sheet.tables:
first_table = first_sheet.tables[0]
print(f"First table name: {first_table.name}")
print("Table data (first 5 rows):")
for row_idx, row in enumerate(first_table.rows()):
if row_idx >= 5: break
print(f" Row {row_idx}: {[cell.value for cell in row]}")
else:
print("First sheet has no tables.")
else:
print("Document has no sheets.")
except FileNotFoundError:
print(f"Error: The file '{file_path}' was not found. Please create a simple .numbers file or adjust the path.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingIn version 4.0, the methods `Document.sheets()` and `Sheet.tables()` were removed. You must now access `sheets` and `tables` as properties.fixReplace `doc.sheets()` with `doc.sheets` and `sheet.tables()` with `sheet.tables`.
affects: >=4.0.0
deprecatedThe `image_data` and `image_filename` methods were deprecated in version 4.0 and replaced by the `cell_style` property for background image data. They will be removed in a future version.fixUse the `cell_style` property to manage background image data.
affects: >=4.0.0
gotchaPassword-encrypted Numbers documents cannot be opened and will raise an `UnsupportedError`. You must remove the password manually in Numbers before parsing.fixOpen the .numbers file in Apple Numbers and save it without a password.
affects: All versions
gotchaWriting to existing Numbers files is not recommended, as `numbers-parser` may not perfectly replicate all original formatting or features. It is safer to save new data to a *new* file.fixAlways save modified or new data to a new `.numbers` file instead of overwriting the source document.
affects: All versions (stable since 3.4.0, but still a best practice)
gotcha`python-snappy` (a dependency) requires platform-specific binary libraries for snappy compression. Installation may require additional OS-level package manager commands (e.g., `libsnappy-dev` on Linux, Homebrew's `snappy` on macOS, or specific pre-compiled wheels on Windows).fixRefer to the `numbers-parser` documentation or `python-snappy`'s GitHub for detailed OS-specific installation instructions (e.g., `brew install snappy` for macOS, `sudo apt-get install libsnappy-dev` for Debian/Ubuntu). Ensure `snappy` binaries are available in your system path or linked correctly.
affects: All versions
gotchaFormulas cannot be written to a document. Pivot tables are unsupported, and saving a document with a pivot table issues an `UnsupportedWarning`.fixAvoid attempting to write formulas or manipulate pivot tables directly with `numbers-parser`. If saving, ensure no pivot tables are present in the document if you wish to avoid warnings.
affects: All versions
gotchaNumberCell values are limited to 15 significant figures to match Apple Numbers' floating-point implementation. Attempting to write a number with more than 15 significant digits results in a `RuntimeWarning` and rounding.fixBe aware of floating-point precision limits. `numbers-parser` will round values to 15 significant figures. Adjust input data if exact precision beyond this limit is critical.
affects: >=4.0.0
Errors
Common errors & fixes
No module named 'snappy'
The `python-snappy` package, a dependency of `numbers-parser`, requires native binary libraries which are not always automatically installed or found by `pip` on all operating systems.
fixEnsure `snappy`'s binary dependencies are installed on your system. For macOS, use `brew install snappy`. For Debian/Ubuntu Linux, use `sudo apt-get install libsnappy-dev`. For Windows, you may need to find pre-compiled `python-snappy` wheels or build from source.
AttributeError: 'Document' object has no attribute 'sheets' (or 'tables')
You are likely trying to call `doc.sheets()` or `sheet.tables()` as methods, which were removed in version 4.0. They are now properties.
fixAccess `sheets` and `tables` as properties: `doc.sheets` and `sheet.tables`.
numbers_parser.exceptions.UnsupportedError: Document is password-protected
`numbers-parser` cannot open Apple Numbers documents that are protected by a password.
fixOpen the `.numbers` file in Apple Numbers and save it without a password before attempting to parse it with `numbers-parser`.
RuntimeWarning: Cannot parse image filename with UTF-8 characters; returned None
This warning occurs on Python versions older than 3.11 when image filenames within the Numbers document contain UTF-8 characters, due to a limitation in Python's `ZipFile` module.
fixUpgrade to Python 3.11 or newer to correctly handle such filenames, or avoid documents with UTF-8 characters in image filenames.
Upgrade
Version history
4.18.5latest on PyPI · released May 18, 2026
Audit
Dependencies
python-snappyrequiredRequired for snappy compression/decompression of '.iwa' files within Numbers documents. Its underlying binary libraries need to be installed separately based on OS.