paper-xlsx

An openpyxl fork for creating workbooks and safely editing existing ones without changing your imports.

paper-xlsx is a fork of openpyxl for creating and editing Excel workbooks. It keeps the openpyxl import name, reader, object model, and formula tokenizer. For loaded editable OOXML workbooks it uses a preserve-mode save path, because stock openpyxl regenerates the whole file from its in-memory model and can destroy content the model does not cover.

import openpyxl   # the import name is unchanged

Under preserve mode, the default, the original file's bytes are the source of truth. Edits are spliced into those bytes; untouched content is copied through unchanged. Operations that cannot be completed safely raise a typed PaperRefusal.

vs openpyxl

High-level changes relative to openpyxl 3.1.5, and why.

Guide

Loading, saving, editing, computation, and errors in paper-xlsx.

API reference

The complete paper-xlsx 0.2.1 public API, including inherited openpyxl APIs.

GitHub

Source, issues, and discussions.

PyPI

pip install paper-xlsx

Quick start

pip uninstall -y openpyxl paper-xlsx
pip install paper-xlsx
paper-xlsx-doctor                       # verify the install

Build a small model, reload it, and make an edit with a machine-readable receipt:

from openpyxl import Workbook, load_workbook

wb = Workbook()
ws = wb.active
ws["A1"], ws["B1"] = "Growth rate", 0.05
ws["A2"], ws["B2"] = "Revenue", 1000
ws["B3"] = "=B2 * (1 + B1)"
wb.save("model.xlsx")

wb = load_workbook("model.xlsx")        # preserve mode is the default

wb.sheetnames                           # inspect structure directly
wb.active["B1"] = 0.07                  # use the standard openpyxl API
receipt = wb.save("model_v2.xlsx", receipt=True)
receipt.to_dict()["cells_changed"]
# {'xl/worksheets/sheet1.xml': {'B1': 'changed', 'B3': 'changed'}}

When the save planner cannot preserve a requested edit safely, validation or save raises a typed PaperRefusal before writing the destination file.

Compatibility

PyPI distribution and GitHub repository: paper-xlsx
Python import: openpyxl. Never import paper_xlsx.
Fork version: openpyxl.__paper_version__
Upstream base: openpyxl 3.1.5 (tag paper-base; upstream releases are merged, not rebased)

pandas uses this fork automatically: preserve mode covers files pandas opens for editing, and new ExcelWriter output uses stock behavior. CI tests Python 3.9–3.13 on Linux, Python 3.13 on Windows, and Python 3.13 on Linux without lxml.