How to Set Up IronPdfEngine

Which Deployment Mode Should You Use?

IronPdfEngine supports two deployment approaches: local and remote. Choosing between them depends on the architecture of your application.

Local mode (the default) is the right choice for standalone applications, desktop tools, and single-server deployments. IronPDF for Java starts IronPdfEngine automatically as a subprocess — no separate infrastructure is needed. Within local mode there are two options for obtaining the IronPdfEngine binaries: download them at first run or bundle them as a Maven dependency.

Remote mode fits distributed systems where a single IronPdfEngine instance serves multiple application nodes. It is also the preferred approach for Docker-based deployments, Kubernetes pods, air-gapped networks that cannot download binaries at runtime, and any scenario where centralizing PDF processing reduces per-service overhead.

The sections below cover both modes in detail.

How Do You Set Up Local IronPdfEngine?

Two options exist for running IronPdfEngine locally. Both produce the same runtime behavior — the difference is when and how the engine binary arrives on the target machine.

//: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>

//: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 Connect to a Remote IronPdfEngine?

Remote mode lets multiple application instances share a single IronPdfEngine server over gRPC. This is common in microservice architectures, containerized deployments, and environments where PDF processing is centralized.

: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);

: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);

//: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");
    }
}

How Do You Check, Stop, or Restart IronPdfEngine?

IronPdfEngine's lifecycle is automatic: it starts on the first IronPDF call and stops when your application shuts down, so most applications never manage it directly. Long-running services (web applications and daemons) are the exception. If the engine is interrupted by something outside IronPDF's control, such as a remote host restart, an operating system kill, or a native crash, you can detect the dead engine and force a clean reconnect with the static, thread-safe methods on IronPdfEngineManager.

IronPdfEngineManager exposes four methods:

• isEngineActive(): Returns true only when the engine is connected and answers a handshake. It never starts the engine, so it is safe to poll.
• startEngine(): Starts and connects the engine, the same as the first IronPDF call does. It is a no-op if the engine is already healthy.
• stopEngine(): Stops the local subprocess, or closes the connection in remote mode. The engine restarts on the next IronPDF call, or immediately with startEngine().
• restartEngine(): Stops the engine, then establishes a fresh connection. This is the recommended recovery action because it clears stale connection state that an ordinary IronPDF call would keep.

The watchdog pattern below recovers automatically if the engine was interrupted, then continues normal work:

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

// Recover automatically if IronPdfEngine was interrupted (host restart, crash, or kill)
if (!com.ironsoftware.ironpdf.IronPdfEngineManager.isEngineActive()) {
    com.ironsoftware.ironpdf.IronPdfEngineManager.restartEngine();
}

// Continue as normal; the engine is now guaranteed to be connected
com.ironsoftware.ironpdf.PdfDocument pdf =
    com.ironsoftware.ironpdf.PdfDocument.renderHtmlAsPdf("<h1>Hello World</h1>");
pdf.saveAs("output.pdf");

What Are the Next Steps?

With IronPdfEngine configured, the full IronPDF for Java feature set is available — HTML to PDF, PDF editing, merging, stamping, and more.

• Start rendering HTML to PDF in Java — step-by-step examples for the most common conversion scenarios
• Explore the IronPDF for Java tutorials — deeper guides covering watermarks, headers and footers, forms, and digital signatures
• Download IronPDF for Java and start a free trial — full-featured trial with no time limit on development use
• Purchase a license for production deployment — perpetual and subscription options with source code access