How to patch a model workbook after upgrading Autory¶
Why patch a workbook?¶
Patching an Autory model workbook is necessary when new features are added to Autory that require updates in the model workbook. It updates the tables, named ranges, etc. in the model workbook to ensure compatibility with the latest version of Autory. Note that this makes your model files incompatible with older versions of Autory, so if you still need to run your model on an older Autory, you may choose not to patch it yet. New features might not be accessible until the optional patches have been applied.
When to patch a workbook¶
This is typically done directly after installing a newer version of Autory.
For major upgrades (e.g., from 3 to 4), patches may be required.
Autory 3 requires model workbooks patched to at least patch 160.
If your workbook is older, run autory patch before running the model.
For minor upgrades (e.g., from 3.1 to 3.2 or from 3.1.0 to 3.1.1), patches are optional.
Not every upgrade contains workbook patches.
For more information about Autory upgrades, see the upgrade guide.
Forward compatibility is not guaranteed¶
Autory logs a warning when it encounters a model workbook that was already patched by a newer version of Autory. This warning does not necessarily prevent the model from running, because a patch might only affect a specific feature. However, forward compatibility (i.e. using older versions of Autory with newer model workbooks) is not guaranteed, so the run might fail or produce incorrect results if the older Autory does not understand the workbook changes.
Therefore, if you need to share a model workbook with someone who still uses an older version of Autory, you might want to postpone the patches, or ask the other person to also upgrade their version of Autory.
autory patch refuses to modify a workbook containing a patch it does not know.
This refusal happens before Autory creates a backup, updates VBA, applies patches, or saves the workbook.
When patching a batch, Autory skips incompatible workbooks, continues with compatible workbooks,
and reports the batch as partially failed.
Steps – using the ribbon¶
- Open the saved, writable model workbook in Excel.
- On the Autory tab, click Patch in the Model group.
- Wait while Autory saves and closes the workbook, applies patches in a terminal, and reopens it in the same Excel instance.
If patching fails, read the terminal error and press a key to continue. Autory reopens the workbook and confirms whether the original file was restored. A timestamped original-file backup is kept alongside the workbook.
Steps – using the terminal¶
-
Open the folder where your model workbook is saved.

-
Open a terminal.
-
Type
autory patch "Autory Model.xlsx"(use the name of your actual file) and hitEnter.Autory keeps a backup in the same folder, with a name like
Autory Model.YYYYMMDDHHMMSS.original.xlsx. When patching succeeds, continue usingAutory Model.xlsx. The.original.xlsxfile is the copy from before patching.
Apply patches up to a chosen number¶
Use --max-patch to apply pending patches up to and including a chosen patch number:
autory patch --max-patch 175 model.xlsx
Existing patches are never undone. Without this option, all pending patches are applied.
Missing, empty, or invalid patch history¶
To apply patches, a workbook must have a Patches table with at least one data row,
and every recorded PatchNr value must be an integer (not a number stored as text).
A blank or invalid value in any row prevents that workbook from being patched.
If no valid patch number can be determined, Autory reports an error and skips the model.
In run-multiple, patch errors affect only the model in question; other models continue.
When running a model, Autory can ignore invalid rows if another readable patch number establishes compatibility
and meets the minimum required patch.
Gaps, duplicates, and patches recorded out of order produce warnings.
autory patch applies patches after the highest recorded number; it does not repair historical gaps.
Compare damaged history with a known good backup before correcting it.
Verify the results before using them.