> 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/get-started/get-started/python3-custom.md).

# Custom Python wrapper for PDF library integration

Learn how to integrate Apryse with Python on macOS using precompiled libraries or building your own wrappers. Get started with a free trial and expert support. Follow our step-by-step guide now! The A

There are two ways to use Apryse with Python:

* Use pip - the precompiled library for [Python 3.x](/core/get-started/languages/python3.md).
* (less common) Use PDFNet bindings to build your own wrappers.

This guide will help you get started by **building your own wrapper**. You can find more information about [using the precompiled library](/core/get-started/languages/python3.md)

{% tabs %}
{% tab title="macOS" %}

## Custom Python wrapper & macOS PDF library integration

This guide will help you [run Apryse samples](#run-the-samples) and [integrate a free trial of the Apryse SDK into Python applications](#integrate-into-your-application) on macOS. Your free trial includes unlimited trial usage and support from solution engineers.

## Prerequisites

* **Python3** or **Python2** with developer extensions
* **CMake** version ≥ 2.8
* **SWIG** 2.0.4 - 2.0.12 or **SWIG** 3.0.12 or **SWIG** 4.0.2 and above
* Apryse's Python3 PDF library for macOS:

{% code lineNumbers="true" %}

```sh
curl -L -O https://downloads.apryse.com/downloads/PDFNetCMac.zip
unzip PDFNetCMac.zip
```

{% endcode %}

{% hint style="info" %}
**Run Apryse SDK in production**

A commercial license key is required for use in a production environment. Please [contact sales](https://apryse.com/form/contact-sales) to purchase a commercial key or if you need any other license key assistance.
{% endhint %}

{% hint style="warning" %}
**Keep your commercial license key confidential.**

License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).
{% endhint %}

## Initial setup

1. Make a directory to store the wrappers and navigate into that directory.
2. Clone the PDFNet Wrappers project, select the correct branch for your release afterwards. This is typically a numbered release such as `11.11`, `11.12`, `11.13` and `12.0`.

{% code lineNumbers="true" %}

```sh
git clone https://github.com/ApryseSDK/PDFNetWrappers
git checkout <SDK version>
```

{% endcode %}

1. Navigate to `PDFNetWrappers/PDFNetC` and move the downloaded \[PDFNet C/C++ SDK] for macOS(#prerequisites) into that directory and unzip it. Ensure you obtain the right architecture for your Python interpreter. This can be done with these two commands:

{% code lineNumbers="true" %}

```sh
curl -L -O http://www.apryse.com/downloads/PDFNetCMac.zip
unzip PDFNetCMac.zip
```

{% endcode %}

1. Now to move the headers in place, make sure you are in the `PDFNetWrappers/PDFNetC` directory and executeandto move the PDFNet libraries in place.You can delete `PDFNetCMac.zip` to free up space.Your `/PDFNetC` folder should be laid out like this like this:

{% code lineNumbers="true" %}

```sh
mv PDFNetCMac/Headers/ .
```

{% endcode %}

{% code lineNumbers="true" %}

```sh
mv PDFNetCMac/Lib/ .
```

{% endcode %}

{% code lineNumbers="true" %}

```sh
PDFNetC
├── Headers
├── Lib
├── PDFNetCMac
└── README.txt
```

{% endcode %}

1. Make a build directory inside `/PDFNetWrappers` and navigate to it. This guide will assume the build directory is called Build.
2. ExecuteIf all goes well, you should get a message which reads:

{% code lineNumbers="true" %}

```sh
cmake -D BUILD_PDFNetPython=ON ..
```

{% endcode %}

{% code lineNumbers="true" %}

```sh
Build files have been written to ~/PDFNetWrappers/Build
```

{% endcode %}

1. Execute `make` followed by `sudo make install`.
2. Next we need to fix the `rpaths` issue on Mac. While still in the same `Build` directory, execute these lines:

{% code lineNumbers="true" %}

```sh
cp ../fix_rpaths.sh ../PDFNetC/Lib/
cd ../PDFNetC/Lib/
sudo sh ./fix_rpaths.sh
```

{% endcode %}

1. Get your Apryse trial key.

{% @apryse-license-key/apryse-license-key platform="SERVER" variant="full" %}

You are now ready to [run the samples](#run-the-samples) or [integrate Apryse SDK into your own application](#integrate-into-your-application).

{% hint style="info" %}
Also check out the source for the PDFNetC wrappers [here](https://github.com/PDFTron/PDFNetWrappers/).
{% endhint %}

## Run the samples

**Running a specific sample**

1. Navigate to the `PYTHON` folder in the sample, for example `/Samples/AddImageTest/PYTHON` and execute `./RunTest.sh`.

**Run all samples**

1. To run all tests, navigate to `/Samples` and executeThe tests will run one by one.

{% code lineNumbers="true" %}

```sh
./runall_python.sh
```

{% endcode %}

{% hint style="info" %}
Output files will be in `/Samples/TestFiles/Output`
{% endhint %}

## Integrate into your application

This section will show you how to use our SDK to create a simple Apryse "Hello World!" application. It will create a document with one blank page and save it as a [linearized PDF](https://apryse.com/blog/pdf-format/what-is-pdf-linearization) in its running directory.

1. Navigate to the `/Samples` directory and create a new directory called `myApp` (if it does not exist already). This guide will assume your application is named myApp. For organization, create a new directory inside `myApp` called `PYTHON`.
2. Navigate inside that `PYTHON` directory and create a new Python file called `myApp.py`. Open it with your favorite text editor and paste this into it:

{% code lineNumbers="true" %}

```python
import site
# below is the relative path to Apryse PDFNetC libraries
site.addsitedir("../../../PDFNetC/Lib")
import sys
from PDFNetPython import *

def main():
    PDFNet.Initialize("YOUR_APRYSE_LICENSE_KEY")
    doc = PDFDoc()
    page = doc.PageCreate()         # Start a new page
    doc.PagePushBack(page)          # Add the page to the document
    doc.Save("output.pdf", SDFDoc.e_linearized);  # Save the document as a linearized PDF
    print("Hello World!")

if __name__ == '__main__':
    main()
```

{% endcode %}

1. Run your application via `python myApp.py`. If all goes well your output should read:

{% code lineNumbers="true" %}

```sh
PDFNet is running in demo mode.
Permission: write
Hello World!
```

{% endcode %}

Check the `output.pdf` that the program output in the same directory. It should be a PDF with one blank page.

## Next step

<a href="https://github.com/iKettles/apryse-gitbook/tree/main/core/guides/README.md" class="button primary">Guides</a><a href="/core/get-started/samples.md" class="button primary">Samples</a>

{% hint style="info" %}
**Also check out the source for the PDFNetC wrappers.**
{% endhint %}

## Troubleshooting

Check the [troubleshooting page](/core/get-started/faq.md) and our [PDFNetWrappers github](https://github.com/PDFTron/PDFNetWrappers/) if you run into any issues going through this document.
{% endtab %}

{% tab title="Windows" %}

## Custom Python wrapper & Windows PDF library integration

This guide will help you [run Apryse samples](#run-the-samples) and [integrate a free trial of the Apryse SDK into Python applications](#integrate-into-your-application) on Windows. Your free trial includes unlimited trial usage and support from solution engineers.

## Prerequisites

* [Python 2.7 or 3.x](https://www.python.org/downloads/).Make sure the executable name is `python.exe`
* [cmake >= 2.8](https://cmake.org/download/).
* [SWIG 2.0.4 - 2.0.12 OR SWIG 3.0.12 OR SWIG 4.0.2 and above](https://sourceforge.net/projects/swig/files/swigwin/).
* [Visual Studio](https://visualstudio.microsoft.com/vs/older-downloads/).
* Clone the PDFNet Wrappers project, select the correct branch for your release afterwards. This is typically a numbered release such as `11.11`, `11.12`, `11.13` and `12.0`.
*

{% code lineNumbers="true" %}

```sh
git clone https://github.com/ApryseSDK/PDFNetWrappers.git
git checkout <SDK Version>
```

{% endcode %}

* Apryse's Python PDF library for Windows:

{% @apryse-download-button/apryse-download-button id="C\_C\_64\_bit\_C\_NET\_Core\_core\_windows" title="Download 64-bit" showVersion="true" %}

{% @apryse-download-button/apryse-download-button id="C\_C\_32\_bit\_Java\_32\_bit\_C\_NET\_Core\_core\_windows" title="Download 32-bit" showVersion="true" %}

Make sure Python, cmake and SWIG are all added to your `path` environment variable.

{% hint style="info" %}
**Run Apryse SDK in production**

A commercial license key is required for use in a production environment. Please [contact sales](https://apryse.com/form/contact-sales) to purchase a commercial key or if you need any other license key assistance.
{% endhint %}

{% hint style="warning" %}
**Keep your commercial license key confidential.**

License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).
{% endhint %}

## Initial setup

1. Extract the `PDFNetWrappersWinXX` folder from the .zip file. This guide will assume it has been extracted to the current user's `Desktop`.
2. From the extracted folder, copy the `Lib` and `Headers` folders and paste them into `PDFNetWrappers-master/PDFNetC/`
3. Create a new folder called `Build` inside the `PDFNetWrappers` folder and enter it.This is what the current directory structure should look like:

![](https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2Fgit-blob-e277cd72f0bcb6810331c268ab5f9f900d9fe6f1%2Fc44492fe34aefd6c46fa8885dc957651e6702260-332x267.png?alt=media)

4. Open a Command Prompt here and run the following:

{% code lineNumbers="true" %}

```sh
cmake -D BUILD_PDFNetPython=ON ..
```

{% endcode %}

This will choose a default Visual Studio version to build the projects for. Wait for the bindings to finish. The output should end with something like this:

{% code lineNumbers="true" %}

```sh
-- Build files have been written to: C:/Users/User_Name/Desktop/PDFNetWrappers-master/Build
```

{% endcode %}

If you see error messages during this process, see the [Troubleshooting](https://docs.apryse.com) section.You should have the following files in your `Build` directory:

![](https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2Fgit-blob-b550a067d67dbcaed3061480943d6e67fe31ec14%2F0ee2017a0d88ff162345473c0c9dbcf52cf8ae27-1082x700.png?alt=media)

5. Open the generated `PDFNetLanguageBindings.sln` with Visual Studio.
6. Change the build mode from `Debug` to `Release`, make sure the appropriate target version (x86 or x64) is selected and build the solution.

{% hint style="info" %}
**Release configuration only**

There is no Debug version of the PDFNet library available.
{% endhint %}

{% hint style="warning" %}
**x64 target missing? Otherwise skip to Step 11.**

Step 7 to step 10 is only required if the x64 target build option is not available. These steps will create the x64 build target and manually copy the dynamic link library output for installation.
{% endhint %}

7. When using the `PDFNetC64` (64-bit) library files then change the build configuration to `x64` in the `Build` dropdown by choosing `Configuration Manager...`.Under `Active Solution Platform`, Select `<New...>` and choose `x64` if `x64` is not displayed as a platform.Click ok then close the modal to exit.
8. Right-click project `PDFNetPython` within Solution Explorer and choose `Properties`.Under `Linker`, select `Command Line` and change `X86` to `X64`.Click ok to exit the modal.
9. Right-click and build the `PDFNetPython` project.This will build the Python library files.
10. Copy the `_PDFNetPython.pyd` dynamic link library file to the `build\lib\Release` folder using the command line below or manually from Windows explorer.This will ensure the Python module which communicates through the dynamic link library can be located for installation.

{% code lineNumbers="true" %}

```sh
copy ".\x64\Release\_PDFNetPython.pyd" ".\lib\Release"
```

{% endcode %}

11. When this is done, select and build the `INSTALL` project.This will install `PDFNetPython` lib files to the `PDFNetWrappers\PDFNetC\lib` folder where it can be located by the samples.
12. Get your Apryse trial key.

{% @apryse-license-key/apryse-license-key platform="SERVER" variant="full" %}

The bindings should be successfully built. You can now run the samples to test out the Apryse SDK.

## Run the samples

Find and enter the `Samples` folder (`PDFNetWrappers-master/Samples`). Here you can find sample code for a large number of features supported by the Apryse SDK.

The output files from all tests are stored in `Samples/TestFiles/output/`

**Run a specific sample**

1. Find the sample you want to run and navigate into the `PYTHON` folder inside.
2. Find `RunTest.bat` and run it. The results should appear on a `cmd` window.

![](https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2Fgit-blob-bf3bf9b80480167a1f26aba72f2b71e76b3055ef%2F4f4488e0f84085282cf60a1dc44881b35f7a0586-1910x694.png?alt=media)

**Run all samples**

1. Find `runall_python.bat` in the samples folder and double click on it to run it. The results should appear on a `cmd` window.

Press any key when a sample ends to start the next one.

![](https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2Fgit-blob-c56d5fcf24dd8828d547d8a21f8fdb693cbebcd2%2Fc2f030658bc77154a1506da2a699bc5808f04969-1671x818.png?alt=media)

## Integrate into your application

This is what we call the "Apryse Hello World" application. It is easy to integrate the rest of Apryse SDK if you are able to open, save and close a PDFDoc.

1. Create a new folder in `Samples` by the name `HelloWorld`.
2. In the `HelloWorld` folder, create a new file called `HelloWorld.py`, open and edit it using your favorite text editor.
3. Insert the following to your file:To test that your code works, run the code using a shell in the `HelloWorld` folder using:Once you have successfully run this, you should see an output file in the working directory of this program.

{% code lineNumbers="true" %}

```python
# You can use the following two lines to use PDFNetPython
# in your solution from anywhere on your system
# so long as you have relative path
import site
site.addsitedir("../../Lib")
import sys

# This is the most important packages to import
# for basic document manipulation.
from PDFNetPython import *

def main():

    # You need to initialize the PDFNet library
    # Before calling any PDF related methods
    PDFNet.Initialize("YOUR_APRYSE_LICENSE_KEY")

    # This example creates a new document
    # and a new page, then adds the page
    # in the page sequence of the document
    doc = PDFDoc()

    page1 = doc.PageCreate()
    doc.PagePushBack(page1)

    # We save the document in a linearized
    # format which is the most popular and
    # effective way to speed up viewing PDFs
    doc.Save(("linearized_output.pdf"), SDFDoc.e_linearized)

    doc.Close()

if __name__ == "__main__":
    main()
```

{% endcode %}

{% code lineNumbers="true" %}

```sh
python.exe -u HelloWorld.py
```

{% endcode %}

## Next step

<a href="https://github.com/iKettles/apryse-gitbook/tree/main/core/guides/README.md" class="button primary">Guides</a><a href="/core/get-started/samples.md" class="button primary">Samples</a>

## Troubleshooting

[Multiple versions of Python](/core/get-started/faq/run-samples-with-multiple-versions-of-python.md) More information for conflict resolution between multiple Python installations.

[CMake Process finding incorrect version](/core/get-started/faq/specify-python-version-for-build.md) Setting specific versions of Python to use for cmake.
{% endtab %}

{% tab title="Linux" %}

## Custom Python wrapper & Linux PDF library integration

This guide will help you [run Apryse samples](#run-the-samples) and [integrate a free trial of the Apryse SDK into Python applications](#integrate-into-your-application) on Linux. Your free trial includes unlimited trial usage and support from solution engineers.

## Prerequisites

* **Python3** or **Python2** with developer extensions
* **CMake** version ≥ 2.8
* **SWIG** 2.0.4 - 2.0.12 or **SWIG** 3.0.12 or **SWIG** 4.0.2 and above
* Apryse SDK for Linux:

{% @apryse-download-button/apryse-download-button id="C\_C\_64\_bit\_C\_NET\_Core\_core\_linux" title="Download 64-bit for Linux" showVersion="true" %}

{% @apryse-download-button/apryse-download-button id="C\_C\_32\_bit\_Java\_32\_bit\_C\_NET\_Core\_core\_linux" title="Download 32-bit for Linux" showVersion="false" %}

{% hint style="info" %}
**Run Apryse SDK in production**

A commercial license key is required for use in a production environment. Please [contact sales](https://apryse.com/form/contact-sales) to purchase a commercial key or if you need any other license key assistance.
{% endhint %}

{% hint style="warning" %}
**Keep your commercial license key confidential.**

License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).
{% endhint %}

## Initial setup

1. Make a directory to store the wrappers and navigate into that directory.
2. Clone the PDFNet Wrappers project, select the correct branch for your release afterwards. This is typically a numbered release such as `11.11`, `11.12`, `11.13` and `12.0`.

{% code lineNumbers="true" %}

```sh
git clone https://github.com/ApryseSDK/PDFNetWrappers
git checkout <SDK Version>
```

{% endcode %}

1. Navigate to `PDFNetWrappers/PDFNetC` and [download the PDFNet C/C++ SDK](/core/get-started/download.md) into that directory. Ensure you obtain the right architecture for your Python interpreter. For example, if your interpreter is 64bit (which this guide will assume), execute

{% code lineNumbers="true" %}

```sh
wget http://www.apryse.com/downloads/PDFNetC64.tar.gz
```

{% endcode %}

1. Unpack `PDFNetC64.tar.gz` by `tar xvzf PDFNetC64.tar.gz`, then executeandto move the PDFNet libraries in place.You can delete `PDFNetC64.tar.gz` to free up space.Your `/PDFNetC` folder should be laid out like this like this:

{% code lineNumbers="true" %}

```sh
mv PDFNetC64/Headers/ .
```

{% endcode %}

{% code lineNumbers="true" %}

```sh
mv PDFNetC64/Lib/ .
```

{% endcode %}

{% code lineNumbers="true" %}

```sh
PDFNetC
├── Headers
├── Lib
├── PDFNetC64
└── README.txt
```

{% endcode %}

1. Make a build directory inside `/PDFNetWrappers` and navigate to it. This guide will assume the build directory is called Build.
2. ExecuteIf all goes well, you should get a message which reads:

{% code lineNumbers="true" %}

```sh
cmake -D BUILD_PDFNetPython=ON ..
```

{% endcode %}

{% code lineNumbers="true" %}

```sh
Build files have been written to ~/PDFNetWrappers/Build
```

{% endcode %}

1. Execute `make` followed by `sudo make install`. You are now ready to [run the samples](#run-the-samples) or [integrate Apryse SDK into your own application](#integrate-into-your-application).

{% hint style="info" %}
**Also check out the source for the PDFNetC wrappers here.**
{% endhint %}

1. Get your Apryse trial key.

{% @apryse-license-key/apryse-license-key platform="SERVER" variant="full" %}

## Run the samples

**Running a specific sample**

1. Navigate to the `PYTHON` folder in the sample, for example `/Samples/AddImageTest/PYTHON` and execute `./RunTest.sh`.

**Run all samples**

1. To run all tests, navigate to `/Samples` and executeThe tests will run one by one.

{% code lineNumbers="true" %}

```sh
./runall_python.sh
```

{% endcode %}

{% hint style="info" %}
**Output files will be in /Samples/TestFiles/Output**
{% endhint %}

## Integrate into your application

This section will show you how to use our SDK to create a simple Apryse "Hello World!" application. It will create a document with one blank page and save it as a [linearized PDF](https://apryse.com/blog/pdf-format/what-is-pdf-linearization) in its running directory.

1. Navigate to the `/Samples` directory and create a new directory called `myApp` (if it does not exist already). This guide will assume your application is named myApp. For organization, create a new directory inside `myApp` called `PYTHON`.
2. Navigate inside that `PYTHON` directory and create a new Python file called `myApp.py`. Open it with your favorite text editor and paste this into it:

{% code lineNumbers="true" %}

```python
import site
# below is the relative path to Apryse PDFNetC libraries
site.addsitedir("../../../PDFNetC/Lib")
import sys
from PDFNetPython import *

def main():
    PDFNet.Initialize("YOUR_APRYSE_LICENSE_KEY")
    doc = PDFDoc()
    page = doc.PageCreate()         # Start a new page
    doc.PagePushBack(page)          # Add the page to the document
    doc.Save("output.pdf", SDFDoc.e_linearized);  # Save the document as a linearized PDF
    print("Hello World!")

if __name__ == '__main__':
    main()
```

{% endcode %}

1. Run your application via `python myApp.py`. If all goes well your output should read:

{% code lineNumbers="true" %}

```sh
PDFNet is running in demo mode.
Permission: write
Hello World!
```

{% endcode %}

Check the `output.pdf` that the program output in the same directory. It should be a PDF with one blank page.

## Next step

<a href="https://github.com/iKettles/apryse-gitbook/tree/main/core/guides/README.md" class="button primary">Guides</a><a href="/core/get-started/samples.md" class="button primary">Samples</a>

{% hint style="info" %}
**Also check out the source for the PDFNetC wrappers.**
{% endhint %}

## Troubleshooting

Check the [troubleshooting page](/core/get-started/faq.md) and our [PDFNetWrappers github](https://github.com/PDFTron/PDFNetWrappers/) if you run into any issues going through this document.
{% endtab %}
{% endtabs %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.apryse.com/core/get-started/get-started/python3-custom.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.