Skip to content

Preserving Excel templates without Excel installed

The problem

Many teams keep a polished Excel template under version control, fill in a few input cells from Python, and expect the output workbook to keep its pivots, charts, slicers, macros, document properties, and relationships intact.

That is harder than it sounds in a headless service:

  • openpyxl loads and saves the workbook through a Python object model. That full-DOM save can rewrite package parts that your script did not intend to edit. In complex templates, some charts, slicers, pivot layout state, or related workbook parts can be lost or can trigger Excel repair prompts.
  • xlwings can preserve the live workbook because it drives a real Excel application. That is the right preservation model for desktop automation, but it requires Excel installed through Windows COM or macOS AppleScript. It does not fit headless Linux servers, CI jobs, Kubernetes pods, or minimal containers.

The WolfXL approach

WolfXL's modify mode is designed for the server-side template-editing case. Open an existing .xlsx or .xlsm file with wolfxl.load_workbook(path, modify=True), change the cells or supported workbook parts you own, and save the result.

In supported modify-mode workflows, WolfXL parses the workbook, applies only the queued cell and supported metadata changes, and writes untouched ZIP entries back byte-identical. That means template parts your script does not touch, such as VBA package parts, drawings, relationships, and existing workbook metadata, stay in the package instead of being reconstructed through a full object-model save.

Because WolfXL does not automate Excel, the same code runs anywhere Python runs, including Linux containers and CI workers.

Code example

import wolfxl

input_path = "finance-template.xlsx"
output_path = "finance-report.xlsx"

wb = wolfxl.load_workbook(input_path, modify=True)
ws = wb["Inputs"]

ws["B2"] = "North America"
ws["B3"] = 2026
ws["B4"] = 1_250_000

wb.save(output_path)

Use wolfxl.load_workbook(path, modify=True) for existing templates. Use wolfxl.Workbook() only when you are creating a new workbook from scratch, where there are no template parts to preserve.

For a measured small-edit workload, updating 3 cells in a 20,000-row workbook took 0.19s with WolfXL modify mode versus 10.9s with openpyxl. Treat that as a scoped benchmark, not a universal speed promise: modify-mode speedups are measured when only a small fraction of cells change, and results vary with workbook shape, file complexity, hardware, and which package parts your workflow edits. Validate against your own representative files before migrating.

Honest boundaries

WolfXL preserves templates by avoiding unnecessary rewrites, but it does not make Excel behavior disappear. Keep these boundaries in your migration checklist:

  • Pivot layout edits are supported in modify mode, but WolfXL stamps refreshOnLoad="1" so Excel rebuilds derived pivot cache records when the file opens. WolfXL does not recalculate pivotCacheRecords internally.
  • OLAP and external pivot caches are unsupported for refresh or cache regeneration. Keep those templates on an Excel-owned refresh path if the cache contents must be live.
  • Chart cached values may be rebuilt by Excel the first time the workbook opens. Treat chart rendering as Excel-derived output, not as a WolfXL-calculated artifact.
  • Validate business-critical templates against your own acceptance files before migration. Include the exact pivots, slicers, charts, macros, external links, and review steps your team depends on.

See also Openpyxl Parity Limitations for the current caveats and performance-claim guardrails.

When xlwings is still the right tool

Choose xlwings when your workflow needs a live Excel process, such as:

  • Excel's calculation engine, including workbook-specific formula behavior that must be recalculated before save.
  • COM-only or AppleScript-only automation features.
  • Add-ins, desktop prompts, protected workflow steps, or other behavior that only exists inside the Excel application.

Use WolfXL when the job is a headless, server-side edit to a supported Excel package and your acceptance tests prove the untouched template parts remain intact.