> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/core/ms-office/compare-docx.md).

# Compare Word documents in a DOCX file

Here is your guide explaining how to perform a semantic comparison on MS Word files using Apryse SDK.

{% hint style="info" %}
**Requirements**

*These packages are required to use these features in production. Trial keys have unlimited access to all features*

<a href="https://apryse.com/capabilities#Compare" class="button primary">Package: Compare</a>
{% endhint %}

Apryse SDK's DOCX Compare utility compares two Microsoft Word documents and produces an output DOCX document in which every difference between them is recorded as a tracked change. DOCX Compare can be used to:

* Review edits between revisions.
* Build an audit trail of what changed.
* Hand an editable, annotated document back to an author.

Because the output is a plain DOCX file, the differences can be viewed, accepted, or rejected in any DOCX editor.

The older version of the input Word document is called the **original** document, while the newer version is the **revised** document. The differences are always expressed relative to the original: content that exists only in the revised document is recorded as a tracked insertion, and content that exists only in the original document is recorded as a tracked deletion.

The comparison runs entirely within the Apryse SDK with no external or system dependencies. Results are deterministic and identical across Windows, Linux, macOS, and Android.

## How DOCX Compare works

The comparison operates directly on the DOCX file format:

* **Text diffing:** The algorithm used for text comparison produces diffs that read naturally, instead of an optimally minimal diff.
* **Broad document coverage:** In addition to the main body text, the comparison also examines auxiliary content, including tables, lists, headers, footers, and styles.
* **Formatting changes:** Differences in text, style, and table formatting are captured as tracked formatting changes, distinct from insertions and deletions.

## Usage

The DOCX Compare method takes the paths to the original and revised DOCX files and the path where the output DOCX will be written. It returns a result object describing the outcome of the comparison.

{% tabs %}
{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
DOCXCompareOptions options;

DOCXCompareResult result = DOCXCompare::Compare(
  "original.docx",
  "revised.docx",
  "output_with_changes.docx",
  &options);
```

{% endcode %}
{% endtab %}

{% tab title="C#" %}
{% code lineNumbers="true" %}

```csharp
DOCXCompareOptions options = new DOCXCompareOptions();

DOCXCompareResult result = DOCXCompare.Compare(
    "original.docx",
    "revised.docx",
    "output_with_changes.docx",
    options);
```

{% endcode %}
{% endtab %}

{% tab title="Go" %}
{% code lineNumbers="true" %}

```go
options := NewDOCXCompareOptions()

result := DOCXCompareCompare(
    "original.docx",
    "revised.docx",
    "output_with_changes.docx",
    options)
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
DOCXCompareOptions options = new DOCXCompareOptions();

DOCXCompareResult result = DOCXCompare.compare(
    "original.docx",
    "revised.docx",
    "output_with_changes.docx",
    options);
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
DOCXCompareOptions options;

DOCXCompareResult result = DOCXCompare::Compare(
    "original.docx",
    "revised.docx",
    "output_with_changes.docx",
    &options);
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
DOCXCompareOptions options;

DOCXCompareResult result = DOCXCompare::Compare(
    "original.docx",
    "revised.docx",
    "output_with_changes.docx",
    &options);
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```js
const options = await PDFNet.DOCXCompare.createDOCXCompareOptions();

const result = await PDFNet.DOCXCompare.compare(
    "original.docx",
    "revised.docx",
    "output_with_changes.docx",
    options
);
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
options = DOCXCompareOptions()

result = DOCXCompare.Compare(
    "original.docx",
    "revised.docx",
    "output_with_changes.docx",
    options)
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code lineNumbers="true" %}

```php
$options = new DOCXCompareOptions();

$result = DOCXCompare::Compare(
    "original.docx",
    "revised.docx",
    "output_with_changes.docx",
    $options);
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}
{% code lineNumbers="true" %}

```ruby
options = DOCXCompareOptions.new()

result = DOCXCompare.Compare(
    "original.docx",
    "revised.docx",
    "output_with_changes.docx",
    options)
```

{% endcode %}
{% endtab %}

{% tab title="VB" %}
{% code lineNumbers="true" %}

```vb
Dim options As New DOCXCompareOptions()

Dim result As DOCXCompareResult = DOCXCompare.Compare(
    "original.docx",
    "revised.docx",
    "output_with_changes.docx",
    options)
```

{% endcode %}
{% endtab %}

{% tab title="Obj-C" %}
{% code lineNumbers="true" %}

```objc
PTDOCXCompareOptions *options = [[PTDOCXCompareOptions alloc] init];

PTDOCXCompareResult *result = [PTDOCXCompare Compare: @"original.docx"
                          revised_docx_path: @"revised.docx"
                                output_path: @"output_with_changes.docx"
                                    options: options];
```

{% endcode %}
{% endtab %}
{% endtabs %}

The `options` argument is optional in some languages. When omitted, the comparison uses default settings.

Alternatively, the function `CompareWithFilter` can be used if the documents are not on disk.

#### Handling documents that already contain tracked changes

If either input document already contains tracked changes, the changes are automatically accepted before the comparison is performed, so the comparison reflects the final resolved text of each document. The resulting object reports whether each input contained pre-existing tracked changes.

#### Comparison result

Both `Compare` and `CompareWithFilter` return a `DOCXCompareResult` object with information about the comparison.

#### Comparison options

The comparison can be customized via a `DOCXCompareOptions` object, which controls how the resulting tracked changes are authored and how certain content is interpreted.

`RevisedAuthor` sets the author name recorded on the tracked changes in the output document. If it is not set, the author is taken from the *last modified by* value in the revised document's metadata. If that value is unavailable, the fixed author string `"Comparison"` is used.

The date stamped on the tracked changes can be controlled in two ways:

* `SetRevisedDate` sets an explicit date, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss`).
* Alternatively, `SetDateMode` selects how the date is determined automatically:
  * `e_revised_save_date` *(default)* — Use the save date recorded in the revised document's metadata.
  * `e_current_date` — Use the current date and time.
  * `e_empty_date` — Leave the date empty.

`TreatStruckoutTextAsDeleted` controls how text that carries strikeout formatting is handled.

* When this option is `false` (the default), text whose only change is the addition of strikeout formatting is reported as a tracked formatting change.
* When this option is `true`, both input documents are pre-processed to remove struck-out text before comparison, so that such text is instead reported as a tracked deletion.

For example, suppose the original document contains the text `ABC`, and the revised document contains the same `ABC` but struck out. With the option disabled, this appears as a formatting change; with the option enabled it appears as a deletion.

## Error handling

For comparison failures, like an invalid revised date or a malformed input document, an exception is thrown. Wrap comparison calls in the appropriate error-handling construct for your language and handle the failure accordingly.

## Sample

[Sample code](/core/get-started/samples/docxcomparetest.md)

View the DOCX Compare sample code in C#, Go, Java, C++, Javascript, Python, PHP, Ruby, VB, and Objective-C.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.apryse.com/core/ms-office/compare-docx.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.