--- title: "Process documents with Document Engine and Python" canonical_url: "https://www.nutrient.io/sdk/document-engine/getting-started/python/" md_url: "https://www.nutrient.io/sdk/document-engine/getting-started/python.md" last_updated: "2026-05-20T19:49:34.959Z" description: "Master PDF document processing with Document Engine. Follow our guide for step-by-step instructions on how to process and merge PDF documents using HTTP API and Python." --- # Process documents with Document Engine and Python This guide walks you through the steps necessary to start Document Engine. It also shows you how to use it to process documents. By the end, you’ll be able to merge two PDF documents into one using Document Engine’s HTTP API from Python. ## Requirements Document Engine is compatible with a range of platforms. Below is the list of supported operating systems. - **macOS**: - Ventura - Monterey - Mojave - Catalina - Big Sur - **Linux**: - Ubuntu, Fedora, Debian, and CentOS - Ubuntu and Debian derivatives (such as Kubuntu, Xubuntu) are also supported **Processor requirements**: - 64-bit Intel (x86_64) processors - ARM (AArch64) processors **Minimum system requirements**: - At least 4GB of RAM, regardless of the operating system ## Installing Docker Document Engine is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system. ### macOS Install and start Docker Desktop for Mac. For detailed instructions, refer to the [Docker website](https://docs.docker.com/docker-for-mac/install/). ### Windows Install and start Docker Desktop for Windows. For detailed instructions, refer to the [Docker website](https://docs.docker.com/docker-for-windows/install/). > Document Engine runs as a Linux container. If you’re using Docker Desktop for Windows, ensure it’s configured to work with Linux containers. For detailed steps, refer to the **How do I switch between Windows and Linux containers?** section in the [Docker documentation](https://docs.docker.com/desktop/setup/install/windows-install/). Users with Docker already set up might need to switch from Windows containers to Linux containers for compatibility. ### Linux Install and start Docker Engine. For detailed instructions on how to install Docker Engine for your Linux distribution, refer to the [Docker website](https://docs.docker.com/engine/install/#server). Once you finish installing Docker Engine, follow the [instructions](https://docs.docker.com/compose/install/#install-compose-on-linux-systems) to install Docker Compose. ## Starting Document Engine To start Document Engine, follow the steps below. 1. Open your terminal emulator. ### macOS Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use `Terminal.app` or [iTerm2](https://iterm2.com/). ### Windows Use your code editor’s integrated terminal or [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell?view=powershell-7.5). ### Linux Use the terminal emulator integrated with your code editor or IDE, or the one bundled with your desktop environment. 2. Run the following command to start the Document Engine container: ```sh docker run --rm -t -p 5000:5000 -e API_AUTH_TOKEN=secret pspdfkit/document-engine:1.15.0 ``` This command may take some time to complete depending on your internet connection speed, as it needs to pull the Docker image. You’ll know that Document Engine is successfully running when you see a message similar to the following in your terminal: ``` [info] 2024-02-05 18:56:45.286 Running Document Engine version 1.15.0 ``` Document Engine is now up and running! ## Installing Python The interaction with Document Engine happens through its HTTP API — you send documents and commands in the request and receive the resulting file in the response. To do this, you’ll invoke the API from the Python script. But first, you need to install Python for your operating system: ### macOS To install Python, first you need to install the Xcode Command Line Tools. Install them by running the following command: ```sh xcode-select --install ``` The most direct way to install Python on macOS is via Homebrew. Follow the instructions on the [Homebrew website](https://brew.sh) to install it. Then, to install Python, run: ```sh brew install python ``` Verify the installation by running the following command in the terminal: ``` python3 --version ``` The output should start with `Python 3.9` — you can ignore the rest of the message. > If the output doesn’t match the above, try restarting the terminal app by typing `exit` and opening it again. ### Windows 1. Go to the [Python downloads website](https://www.python.org/downloads/release/python-392/). 2. Scroll down to the bottom of the page until you find the Windows installer (64-bit) entry. Click on the link to download the installer. 3. Open the installer. Make sure to check the Add Python 3.9 to PATH checkbox at the bottom of the window, and click Install Now. 4. Complete the installation process. Now start the terminal and run the `python --version` command. The output should start with `Python 3.9` — you can ignore the rest of the message. ### Linux You can install Python using your distribution’s package manager: ```sh apt-get update && apt-get install -y python3.9 python3-pip && ln -s /usr/bin/python3.9 /usr/bin/python3 ``` ### Fedora/Centos ```sh dnf install -y python3 python3-pip ``` Now run the `python3 --version` command. The output should start with `Python 3.9` — you can ignore the rest of the message. ## Merging PDFs To make HTTP requests to Document Engine’s API, you need an HTTP client library. For this scenario, you’ll use the excellent [Requests](https://requests.readthedocs.io/en/v2.9.1) package. Install it by running the following command: ### macOS ```sh python3 -m pip install requests==2.25.1 ``` ### Windows ```powershell python -m pip install requests==2.25.1 ``` ### Linux ```sh python3 -m pip install requests==2.25.1 ``` Now you can create a script to merge the PDFs. It’ll take two file paths as command-line arguments, send the files to Document Engine to merge them, and save the result in another file on disk. Create a `merge.py` file with the following content: ```merge.py import sys import json import requests if len(sys.argv) < 3: print("Too few arguments.") exit(1) file1 = sys.argv[1] file2 = sys.argv[2] url = "http://localhost:5000/api/build" payload= { "instructions": json.dumps({ "parts": [ { "file": "file1" }, { "file": "file2" } ] })} files=[ ('file1',('file1.pdf',open(file1,'rb'),'application/pdf')), ('file2',('file2.pdf',open(file2,'rb'),'application/pdf')) ] headers = { 'Authorization': 'Token token=secret' } response = requests.post(url, headers = headers, data = payload, files = files) if response.status_code == 200: with open("result.pdf", "wb") as f: f.write(response.content) else: print( f"Request to Document Engine failed with status code {response.status_code}: '{response.text}'." ) ``` The script verifies that the number of arguments is correct and prepares the request data. It includes two files — `file1` and `file2` — and a list of `instructions` for Document Engine. By default, Document Engine’s output for the `/api/build` endpoint is the result of merging all documents or parts of the `instructions`. To learn more about the `/api/build` instructions, go to Document Engine’s [API Reference](https://nutrient.io/api/reference/document-engine/upstream/#tag/Build-API). The rest of the code deals with error handling, and if everything goes well, it saves the result in the `result.pdf` file in the current working directory. You can check how it works in practice yourself! Pick any two PDFs on your computer (or use [file1.pdf](https://www.nutrient.io/assets/nutrient-media/files/cover.pdf) and [file2.pdf](https://www.nutrient.io/assets/nutrient-media/files/document.pdf) if you don’t have any), and run the script: ### macOS ```sh python3 merge.py path/to/file1.pdf path/to/file2.pdf ``` ### Windows ```powershell python merge.py path/to/file1.pdf path/to/file2.pdf ``` ### Linux ```sh python3 merge.py path/to/file1.pdf path/to/file2.pdf ``` > Make sure to replace `path/to/file1.pdf` and `path/to/file2.pdf` with the actual location of the PDF files on your computer. If you used the two files from the links above, you should see a five-page PDF document like what’s shown below. That’s it! Now you know how to use Document Engine's API to perform operations on documents with Python. To learn more about the various operations you can perform on documents with Document Engine, visit Document Engine's [API Reference](https://nutrient.io/api/reference/document-engine/upstream). --- ## Related pages - [Process documents with Document Engine and curl](/sdk/document-engine/getting-started/curl.md) - [Document Engine with Docker](/sdk/document-engine/getting-started/docker-deployment-react-frontend.md) - [Document Engine with Docker and EJS templates](/sdk/document-engine/getting-started/docker-deployment-ejs-templates.md) - [Process documents with Document Engine and Golang](/sdk/document-engine/getting-started/golang.md) - [Getting started with Document Engine](/sdk/document-engine/getting-started.md) - [Process documents with Document Engine and Rust](/sdk/document-engine/getting-started/rust.md) - [Process documents with Document Engine and PHP](/sdk/document-engine/getting-started/php.md)