How to Use Delta Patcher to Apply an XDelta Patch

Before you start

Most patching problems are settled before you open Delta Patcher. Make sure you have these:

• Delta Patcher installed. See the installation guide if you haven’t set it up yet.
• The .xdelta patch, extracted from its .zip, .7z or .rar archive if it came in one.
• The exact original file the patch expects. The patch’s readme usually lists the file name, version or revision, and often a CRC32, MD5 or SHA-1 checksum.
• A spare copy of the original. Delta Patcher replaces the original by default, so keep a backup elsewhere.
• Free disk space of at least the patched file’s size, because the new file is written before the old one is removed.

How to apply an XDelta patch

1. Open Delta Patcher

   Launch the program. It always starts in patch application mode, showing an Original file field and an XDelta patch field. If you see Modified file and Description fields instead, you’re in creation mode; click the switch-mode button at the bottom right to go back.

2. Select the original file

   Click the folder button to the right of Original file and choose the file you want to patch. You can also drag the file from your file manager onto the Delta Patcher window.

   Choose the file itself, not an archive that contains it. If your game or file came in a .zip or .7z, extract it first.

3. Select the XDelta patch

   Click the folder button to the right of XDelta patch and choose the .xdelta file. The file dialog only lists files ending in .xdelta. If your patch has a different extension, see patches with other extensions below.

   Dragging works here too: a dropped file ending in .xdelta goes into the patch field, and anything else goes into the original file field.

4. Read the patch description, if there is one

   When a patch contains a description, Delta Patcher shows it in a Patch info tooltip beside the patch button as soon as you select it. Authors often use it to name the exact source file, so read it before continuing. Patches without a description don’t show anything, which is normal.

5. Set the options

   Click the gear button next to Apply patch. The menu has two checkboxes:

   • Backup original file (off by default): keeps your original untouched and saves the result as a new file with PATCHED added to the name.
   • Checksum validation (on by default): checks the output against the checksums stored in the patch.

   Delta Patcher doesn’t remember these settings, so they reset every time you start it.

6. Click Apply patch

   The window is disabled while xdelta3 rebuilds the file. Small files finish almost instantly; multi-gigabyte disc images can take a while. Don’t close the program in the meantime.

7. Read the result

   “Patch successfully applied!” means every checksum in the patch matched. If you see “The patch could not be applied: The file you are trying to patch is not the right one,” your original doesn’t match the one the patch was made for; go to fixing checksum mismatch errors. Any other failure says “See log for more information.” The log section below shows how to read it.

8. Find and test the patched file

   Open the folder that contains your original file. Depending on the backup option, the patched file either replaced the original or sits beside it with PATCHED in its name. Open it in the program or emulator you use it with. If the patch author published a checksum for the patched file, compare it with yours for certainty.

Where is the patched file?

Delta Patcher never asks where to save the output. It writes the new file into the same folder as the original, and the backup option decides what happens next:

Notice there’s no space before PATCHED. If a program expects a particular file name, rename the result. Disc images with a .cue sheet need extra care, covered in where Delta Patcher saves the patched file.

The two options, explained

Backup original file

Despite the name, this option doesn’t create a separate backup copy. It tells Delta Patcher not to replace the original. Turn it on when:

• you don’t have another copy of the original file;
• you want to compare the original and patched versions;
• you plan to apply other patches to the same original later.

The cost is disk space: both files stay in the folder.

Checksum validation

Most XDelta patches contain a checksum for each block (“window”) of the output. With validation on, xdelta3 checks each rebuilt block against its checksum and stops at the first mismatch, before a broken file can replace your original.

Turning validation off doesn’t make a wrong source file work. It only removes the safety check, so the patch may “succeed” and produce a corrupt file. Leave it on. Here’s when switching it off makes sense (almost never).

Patches with other extensions (.vcdiff, .xdelta3, .delta)

XDelta patches sometimes use extensions other than .xdelta. The format inside is the same, but Delta Patcher’s file dialog only shows .xdelta files, and drag and drop treats other extensions as the original file. The simple fix is to rename the patch so it ends in .xdelta, for example translation.vcdiff → translation.xdelta. Renaming doesn’t change the contents.

This only works for real XDelta/VCDIFF patches. Renaming an IPS, BPS or UPS patch won’t work; see XDelta vs other patch formats for the tools those need.

Applying more than one patch

Some projects ship several patches, such as a base translation plus an optional add-on, or a v1.0 patch followed by a v1.1 update. Each XDelta patch expects the exact file it was created from, so:

1. Apply patches in the order the author specifies.
2. Apply each later patch to the output of the previous one, not to the original.
3. Tick Backup original file each time so you can restart if the order was wrong.

A checksum error on the second patch usually means the order was wrong, or the second patch was meant for the unpatched original. Patches designed as alternatives can’t be stacked.

Using the log

The log is hidden by default. Click the log button at the bottom right of the window to show it. Each message is timestamped, and failures appear as An error has occurred: followed by the message from xdelta3, for example:

[14:32:07] An error has occurred: xdelta3: target window checksum mismatch: XD3_INVALID_INPUT

The part after xdelta3: is what matters for troubleshooting. Search for it on the common errors page, or include it when you ask for help.

Opening patches by double-click

If you set Delta Patcher as the default app for .xdelta files, double-clicking a patch launches the program with that patch already selected. You still choose the original file. The installation guide shows how to set this up on Windows.

Is there a command-line version?

Delta Patcher is a graphical tool with no batch or command-line patching mode. For scripts or automation, use the xdelta3 command-line program. This applies a patch exactly like Delta Patcher does, writing to the output name you choose:

xdelta3 -d -s "Game (USA).iso" translation.xdelta "Game (USA) patched.iso"

-d means decode (apply), -s names the source file, and the last two arguments are the patch and the output. The XDelta guide covers more options.