{"id":8356,"library":"numbers-parser","title":"Apple Numbers Spreadsheet Parser","description":"numbers-parser is a Python module for reading and editing Apple Numbers .numbers files. It supports Numbers files generated by Numbers versions 3.x and later, and is tested against Numbers documents from 10.0 through to 15.1 (as of February 2026). It supports Python versions from 3.10 onwards and is actively maintained.","status":"active","version":"4.18.2","language":"en","source_language":"en","source_url":"https://github.com/masaccio/numbers-parser","tags":["apple numbers","spreadsheet","parser","iwork"],"install":[{"cmd":"pip install numbers-parser","lang":"bash","label":"Basic Installation"},{"cmd":"# macOS (Homebrew Python recommended):\nbrew install snappy python3 pipx\npipx install numbers-parser\n\n# Linux (Debian/Ubuntu):\nsudo apt-get -y install libsnappy-dev\npip install numbers-parser\n\n# Windows (x86 binaries for python-snappy are not readily available on PyPI, consider using pre-compiled wheels or ARM Windows)","lang":"bash","label":"Installation with python-snappy binary dependencies"}],"dependencies":[{"reason":"Required for snappy compression/decompression of '.iwa' files within Numbers documents. Its underlying binary libraries need to be installed separately based on OS.","package":"python-snappy","optional":false}],"imports":[{"symbol":"Document","correct":"from numbers_parser import Document"},{"note":"Accessed as a property of a Document object.","symbol":"Sheet","correct":"from numbers_parser import Document\ndoc = Document('file.numbers')\nsheet = doc.sheets[0]"},{"note":"Accessed as a property of a Sheet object.","symbol":"Table","correct":"from numbers_parser import Document\ndoc = Document('file.numbers')\nsheet = doc.sheets[0]\ntable = sheet.tables[0]"}],"quickstart":{"code":"from numbers_parser import Document\n\n# Create a dummy Numbers file for demonstration\n# In a real scenario, you would have an existing .numbers file.\n# For this quickstart, we'll simulate a file path.\n# Make sure 'mydoc.numbers' exists or replace with a real path.\n# If you don't have one, create a simple one in Apple Numbers and save it.\n\nfile_path = 'example.numbers'\n# You might need to create a simple example.numbers file manually\n# with at least one sheet and one table for this to run.\n# For example, create a new Numbers spreadsheet, add some data to Sheet 1, Table 1, and save as example.numbers.\n\ntry:\n    doc = Document(file_path)\n    sheets = doc.sheets\n    print(f\"Document has {len(sheets)} sheets.\")\n\n    if sheets:\n        first_sheet = sheets[0]\n        print(f\"First sheet name: {first_sheet.name}\")\n\n        if first_sheet.tables:\n            first_table = first_sheet.tables[0]\n            print(f\"First table name: {first_table.name}\")\n            print(\"Table data (first 5 rows):\")\n            for row_idx, row in enumerate(first_table.rows()):\n                if row_idx >= 5: break\n                print(f\"  Row {row_idx}: {[cell.value for cell in row]}\")\n        else:\n            print(\"First sheet has no tables.\")\n    else:\n        print(\"Document has no sheets.\")\nexcept FileNotFoundError:\n    print(f\"Error: The file '{file_path}' was not found. Please create a simple .numbers file or adjust the path.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Replace `doc.sheets()` with `doc.sheets` and `sheet.tables()` with `sheet.tables`.","message":"In version 4.0, the methods `Document.sheets()` and `Sheet.tables()` were removed. You must now access `sheets` and `tables` as properties.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use the `cell_style` property to manage background image data.","message":"The `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.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Open the .numbers file in Apple Numbers and save it without a password.","message":"Password-encrypted Numbers documents cannot be opened and will raise an `UnsupportedError`. You must remove the password manually in Numbers before parsing.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always save modified or new data to a new `.numbers` file instead of overwriting the source document.","message":"Writing 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.","severity":"gotcha","affected_versions":"All versions (stable since 3.4.0, but still a best practice)"},{"fix":"Refer 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.","message":"`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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid 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.","message":"Formulas cannot be written to a document. Pivot tables are unsupported, and saving a document with a pivot table issues an `UnsupportedWarning`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be 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.","message":"NumberCell 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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `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.","cause":"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.","error":"No module named 'snappy'"},{"fix":"Access `sheets` and `tables` as properties: `doc.sheets` and `sheet.tables`.","cause":"You are likely trying to call `doc.sheets()` or `sheet.tables()` as methods, which were removed in version 4.0. They are now properties.","error":"AttributeError: 'Document' object has no attribute 'sheets' (or 'tables')"},{"fix":"Open the `.numbers` file in Apple Numbers and save it without a password before attempting to parse it with `numbers-parser`.","cause":"`numbers-parser` cannot open Apple Numbers documents that are protected by a password.","error":"numbers_parser.exceptions.UnsupportedError: Document is password-protected"},{"fix":"Upgrade to Python 3.11 or newer to correctly handle such filenames, or avoid documents with UTF-8 characters in image filenames.","cause":"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.","error":"RuntimeWarning: Cannot parse image filename with UTF-8 characters; returned None"}]}