How to Set Up IronPdfEngine

Option 1: Download IronPdfEngine at Runtime

By default, after adding the core ironpdf dependency, IronPDF detects the host platform (for example, Windows x64 or Linux x64) on the first run and downloads the matching IronPdfEngine binary from the internet.

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>20xx.xx.xx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>20xx.xx.xx</version>
</dependency>

After the initial download, the binary is cached locally and subsequent runs start without a network call.

Option 2: Bundle IronPdfEngine as a Dependency (Recommended)

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-windows-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-windows-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-windows-x86</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-windows-x86</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-macos-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-macos-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-macos-arm64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-macos-arm64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>

How Do You Verify the Required IronPdfEngine Version?

Version matching is strict — IronPDF for Java 2024.2.2 requires IronPdfEngine 2024.2.2 exactly. Use getIronPdfEngineVersion to confirm the required version before deploying the server:

:path=/static-assets/ironpdf-java/content-code-examples/get-started/use-ironpdfengine-8.java

// Retrieve the IronPdfEngine version required by this Java library build
String ironPdfEngineVersion = Settings.getIronPdfEngineVersion();
System.out.println("Required IronPdfEngine version: " + ironPdfEngineVersion);

Deploy or pull the IronPdfEngine Docker image or binary that matches the returned version string.

How Do You Configure the Remote Connection?

Assume IronPdfEngine is running at 123.456.7.8:33350. Set the host and port before calling any IronPDF method. The best practice is to place these calls at application startup, before any PDF operation:

:path=/static-assets/ironpdf-java/content-code-examples/get-started/use-ironpdfengine-9.java

// Configure IronPDF for Java to connect to a remote IronPdfEngine instance
com.ironsoftware.ironpdf.Settings.setIronPdfEngineHost("123.456.7.8");
com.ironsoftware.ironpdf.Settings.setIronPdfEnginePort(33350);

After these two lines execute, all subsequent IronPDF calls in your application route to the remote server. No local IronPdfEngine subprocess is started, and no platform-specific engine dependency is needed in your pom.xml.

What Does a Complete Remote Setup Look Like?

The following example connects to a remote IronPdfEngine instance and renders an HTML string to a PDF file — the same API used in local mode, with only the configuration differing:

//:path=Main.java
import com.ironsoftware.ironpdf.*;

public class Main {
    public static void main(String[] args) throws Exception {
        // Point the library to the remote IronPdfEngine server
        Settings.setIronPdfEngineHost("123.456.7.8");
        Settings.setIronPdfEnginePort(33350);

        // Render HTML to PDF — IronPdfEngine on the remote host performs the work
        PdfDocument pdf = PdfDocument.renderHtmlAsPdf("<h1>Hello from remote IronPdfEngine</h1>");
        pdf.saveAs("output.pdf");
    }
}

//:path=Main.java
import com.ironsoftware.ironpdf.*;

public class Main {
    public static void main(String[] args) throws Exception {
        // Point the library to the remote IronPdfEngine server
        Settings.setIronPdfEngineHost("123.456.7.8");
        Settings.setIronPdfEnginePort(33350);

        // Render HTML to PDF — IronPdfEngine on the remote host performs the work
        PdfDocument pdf = PdfDocument.renderHtmlAsPdf("<h1>Hello from remote IronPdfEngine</h1>");
        pdf.saveAs("output.pdf");
    }
}

The rendered PDF is returned to the Java process over gRPC and saved locally. The remote server handles all Chrome-based rendering, font loading, and resource resolution.