Convert Microsoft Office files

The Conversion Service uses Microsoft Office applications to process jobs containing Word, Excel, and PowerPoint documents. Select one of the following two options when configuring the Microsoft Office file conversion in the Conversion Service Configurator:

Conversion with a local Microsoft Office installation on the same server.
Conversion using the Office for the web service.

These options differ in configuration parameters, output quality, and performance. Both options extract embedded documents from Office documents in Open XML format (for example, DOCX, XLSX, PPTX) in a destructuring step before conversion. Macro instructions are disabled in all cases.

Choose a Microsoft Office conversion method

To ensure high-quality conversion with accurate layout and visual fidelity, the Conversion Service offers two Microsoft-based processing options: a local Microsoft Office installation or the Office for the web service in Microsoft Azure Cloud. Both options deliver equally high conversion quality, with no significant differences identified in detailed comparisons.

Use the local Microsoft Office installation if you:

Require high performance. Cloud conversion may involve significant overhead for uploading and downloading file contents.
Need to convert large documents (more than 100 MB).
Want to process many large Excel files.
- Only the local installation option supports fit to page in Microsoft Excel.
- Microsoft Excel files with many sheets or hundreds of pages aren't supported in the Office for the web service.
Must repair Word documents.
Work with password-protected documents.
Handle macro-enabled files (XLTM, PPTM, WordML).
Need to use special or custom fonts.
- Fonts can be installed locally but not added to the web service.
- The web service includes more default fonts than a typical Windows server.
Keep data on-premises if required by security policies or if you require a lack of internet access.
- Web service conversions temporarily store files in the Azure cloud. Storage region depends on your subscription.

Use the Convert using the Office for the web service if:

You're converting smaller files (smaller than 100 MB), especially Word documents.
Files were created using Microsoft Office for the web.
You're deploying the Docker version in production.
You prefer lower setup and maintenance overhead.

Convert files using local Microsoft Office installation

caution

To comply with Microsoft licensing, each client submitting Word, Excel, or PowerPoint jobs must be licensed for Microsoft Office. For more information, see Licensing Microsoft Office software in Commercial Licensing on the Microsoft site.

If you want to Convert files using local Microsoft Office installation, you must have a compatible version of Microsoft Office installed on the Conversion Service server:

Office version
Office 2019* (64-bit)
Office 2021 (64-bit)
Office 2024 (64-bit)
Microsoft 365 (64-bit)

* The Pdftools support for Microsoft Office 2019 will end in October 2025.

The supported language is English (United States). The Microsoft Print to PDF virtual printer must also be installed.

Microsoft Office version compatibility

For optimal conversion results, use the same Microsoft Office version that was used to create the documents. The Conversion Service only supports Microsoft Office 2019 and later.

Install and configure local Microsoft Office installation

During Microsoft Office setup, follow these steps and requirements:

Use a static license key (device-based license), especially with Microsoft 365. Avoid user logins to prevent dialog pop-ups that can interrupt processing.
After installation, activate the Office license.
Open sample Word, Excel, and PowerPoint files to confirm there are no blocking pop-ups.
If your documents rely on language features like hyphenation, install the required language packs.

Improve performance with Windows Defender exceptions

If Windows Defender is active, enabling the Windows Defender Rules setting in the Configurator may improve conversion speed. It adds exceptions for specific processes and folders to reduce scanning overhead.

Enable it under Conversion Service > Windows Defender Rules. Windows Defender in Configurator

Make sure group policies don't override these exceptions.

Third-party antivirus software

Third-party tools like Bitdefender may block required operations. To guarantee successful conversion, you must add any application exceptions to your third-party antivirus software.

Set up on Windows

Assign a user account for the local Microsoft Office installation. You can either:

Recommended: Use automatically generated user account
Existing user account

Recommended: Use automatically generated user account

Unless restricted by security policies or domain controllers, let the Conversion Service Configurator create a ConvsrvOfficeUser account with a secure password.

The following settings are applied automatically:

Joins the Users group.
Has encrypted credentials saved through the Windows Data Protection API.
Grants the user Allow log on locally and Log on as a batch job security policies.
Has registry and DCOM permissions for Word, Excel, and PowerPoint.

To set up an automatically generated user account in the Configurator:

In the Conversion Service Configurator, go to Conversion Service tab, and then scroll to the Configuration section.
Next to the Office Conversion, click Configure
Select Local Office Installation and Automatically Create a User Account, and then click Next.
Click Apply, and then in the Changes detected dialog box, click Save & Restart Service.
ConvsrvOfficeUser appears in the username field with a random password. Click Apply.

note

The automatically generated user account is recommended for most servers unless specific security policies or domain controller restrictions apply. This is the case if:

Log on as a batch job security policy is applied.
Allow log on locally security policy is applied.
The server is managed by a domain controller.

Use an existing user account

Use this if your server has strict security rules or is managed through a domain controller.

Requirements:

Create the user account manually (local or domain). The Conversion Service Configurator does not modify this account.
Grant Allow log on locally and Log on as a batch job (or assign to a group with these rights).
Don't assign admin privileges. Set up the user account with minimum user rights (don't assign the user account to the Administrators group).
Update the configuration if the password changes or expires.

These properties and settings are set automatically:

The password is encrypted using the Windows Data Protection API before it is stored in a configuration file.
The registry and DCOM permissions for Word, Excel, and PowerPoint are adjusted.

caution

If using a domain user, disable any group policies enforcing regular password changes. Otherwise, you'll need to reconfigure the Office setup each time the password changes.

To set up an existing user account in the Configurator:

In the Conversion Service Configurator, go to Conversion Service tab, and then scroll to the Configuration section.
Next to the Office Conversion, click Configure
Select Local Office Installation with an Existing User Account, and then click Next.
Enter the username and password for the user account. The Conversion Service accepts all standard formats for Windows users (both Username@domain and domain\Username formats). The Username is automatically resolved to ServerName\Username.
Click Apply, and then in the Changes detected dialog box, click Save & Restart Service.

Set up in Docker container

Send Office documents to another Conversion Service instance of the Conversion Service running on Windows. Office document conversion can be activated as follows:

Set up and run the service on Windows.
Enable Office Conversion in the Processing Steps section of your profile. Note that this is active by default.
When starting the Docker container, set the WINDOWS_SERVICE_ENDPOINT environment variable:
```
docker run -dp 13033:13033 ... \
  -e WINDOWS_SERVICE_ENDPOINT=http://server:13033/conversion/v1.0/rest \
  pdftoolsag/conversion-service
```
Note that if the Windows service uses HTTPS, its host certificate must be trusted by the Docker container. Otherwise, no connection can be established. By default, no trusted certificates are installed.
Copy trusted certificates to /usr/local/share/ca-certificates/.
Run the command update-ca-certificates.

Convert using the Office for the web service

The Office for the web service option converts the documents using a Microsoft Azure Cloud service. Technologies used with this option include the Microsoft Authentication Library (MSAL), the Microsoft Graph API, and the Microsoft Sharepoint API.

The conversion flow:

Upload the file to the user's OneDrive.
Convert the file to PDF.
Delete the uploaded file.

All connections use HTTPS. The service encrypts files before transmitting them over the internet.

caution

You need a valid license to allow the Conversion Service to convert Word, Excel, and PowerPoint documents. This means you must have:

Microsoft 365 for business subscription (Azure Cloud tenant) with a dedicated user account.
Microsoft 365 license for this dedicated user.

You should create a dedicated user account, as full control over this user's OneDrive is requested.

Set up on Windows

Use the Configurator to set up the Office for the web:

In the Conversion Service Configurator, go to Conversion Service tab, and then scroll to the Configuration section.
Next to the Office Conversion, click Configure
Select Office for the web, and then click Next.
Enter the user account login (usually, an email address) for the Microsoft Office for the Web Service in the Username field.
Click Apply, and then in the Changes detected dialog box, click Save & Restart Service.
Sign in to the Microsoft 365 user account in the pop-up window that appears. Enter the password for the user account. If your company has set up 2-factor authentication, enter the authenticator code and click Verify.

Set up in Docker

Enable Office Conversion in the Processing Steps section of your profile. Note that this option is active by default.
Create a persistent volume (for example, convsrv-etc) to store the authentication token cache.
```
docker volume create --name convsrv-etc
```

Create the token cache directory and set permissions. Mount the volume, create the TokenCaches folder, and give the Conversion Service user read and write access.

docker run --rm \
  --mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \
  --user root pdftoolsag/conversion-service \
  bash -c "mkdir /etc/convsrv/TokenCaches && chown convsrv:convsrv /etc/convsrv/TokenCaches"

Initialize the token cache by running the csconfig tool to:

docker run \
  --mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \
  -e SERVICE__OFFICE__TYPE=OfficeWebService \
  -e SERVICE__OFFICE__USERNAME=myuser@myorganization.onmicrosoft.com \
  pdftoolsag/conversion-service \
  bash -c "bin/csconfig office webinit"

To start the Docker container, mount the token cache volume and set the required environment variables.

docker run -dp 13033:13033 \
--mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \
-e SERVICE__OFFICE__TYPE=OfficeWebService \
-e SERVICE__OFFICE__USERNAME=myuser@myorganization.onmicrosoft.com \
pdftoolsag/conversion-service

Set environment variables SERVICE__OFFICE__TYPE and SERVICE__OFFICE__USERNAME according to the configured user and office type.

Troubleshooting

You may encounter problems when setting up and using Office conversion. The issues can be divided into two categories:

Configuration errors
Specific errors related to Word, Excel, and PowerPoint documents

Configuration errors

The following sections include the warnings and errors that you encounter inside the Configurator during configuration and possible solutions.