How to Set Up IronPdfEngine
IronPdfEngine is a gRPC server that performs every PDF operation (creating, editing, reading, and rendering). The IronPDF for Java library is an API wrapper around this server: when your Java code calls any IronPDF method, IronPdfEngine executes the work. By default, IronPDF for Java spawns IronPdfEngine as a local subprocess and manages its lifecycle automatically. For more advanced deployments (shared microservices, Docker containers, or air-gapped networks), you can run IronPdfEngine as a standalone remote server instead.
Quickstart: Set Up IronPdfEngine for JavaMinimal Workflow (5 steps)
- Add the IronPDF dependency to your
pom.xmlfile - Choose a local mode: runtime download or bundled dependency
- For remote mode, use
setIronPdfEngineHostto configure the host address - For remote mode, use
setIronPdfEnginePortto configure the port - Call any IronPDF rendering method; IronPdfEngine handles the PDF work
Settings.getIronPdfEngineVersion() to confirm the required version.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.
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.
<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 1, Runtime Download: Trade-offs
| Advantage | Limitation |
|---|---|
| Smallest application package size | Internet access required on first run |
| Supports multiple target platforms from one artifact | Slower first-run startup while binary downloads |
Option 2: Bundle IronPdfEngine as a Dependency (Recommended)
IronPDF Java provides platform-specific Maven artifacts that bundle IronPdfEngine as a .zip file inside the dependency. The library extracts and uses it automatically, no network call is needed at runtime.
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>Then add the platform artifact for your target environment. Install only the artifact for your target platform, each one is large, and installing all of them unnecessarily inflates the build.
Windows x64
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-windows-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>Windows x86
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-windows-x86</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>Linux x64
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-linux-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>macOS x64
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-macos-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>macOS ARM (Apple Silicon)
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-macos-arm64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>ironpdf and ironpdf-engine-xxx-xxx dependency versions must match exactly. The version string refers to the IronPDF for Java release, not IronPdfEngine's internal version number.Option 2, Bundled Dependency: Trade-offs
| Advantage | Limitation |
|---|---|
| Faster startup, no download step | Larger application package |
| No internet access required after installation | Must specify target platform explicitly |
| Consistent behavior in air-gapped environments | Installing multiple platform artifacts inflates build size significantly |
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.
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:
// 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:
// 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.
33350 is open in any firewalls or security groups between the two.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:
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");
}
}Output
The remote engine renders the HTML and returns the PDF, saved locally.
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(): Returnstrueonly 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 withstartEngine().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:
// 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");isEngineActive() reports IronPDF's own connection state, not operating system processes, so it behaves the same for local and remote engines.IronPdfEngineConnection.withCustomGrpcConnection(...), stopEngine() and restartEngine() throw UnsupportedOperationException because the caller owns the channel and IronPDF cannot rebuild it. isEngineActive() and startEngine() work in every mode.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
Frequently Asked Questions
What is IronPdfEngine and how does it function with IronPDF for Java?
IronPdfEngine is a gRPC server that performs all PDF operations such as creating, editing, reading, and rendering. IronPDF for Java acts as an API wrapper, directing Java code calls to be executed by IronPdfEngine.
What deployment modes are available for IronPdfEngine?
IronPdfEngine supports both local and remote deployment modes. Local mode is ideal for standalone applications and does not require additional infrastructure. Remote mode facilitates distributed systems, centralizing PDF processing for multiple application nodes.
How is IronPdfEngine set up locally?
Local setup involves two options: downloading IronPdfEngine at runtime or bundling it as a platform-specific Maven dependency. The choice affects package size and startup time.
What are the trade-offs of downloading IronPdfEngine at runtime?
Downloading at runtime results in a smaller package size and supports multiple platforms, but it requires internet access for the initial run and the first startup is slower.
Why is bundling IronPdfEngine as a dependency recommended?
Bundling results in faster startups with no need for internet access at runtime, providing consistent behavior in air-gapped environments. However, it increases package size and requires specifying the target platform.
How do you configure IronPDF for a remote connection to IronPdfEngine?
Set the host and port of IronPdfEngine using `setIronPdfEngineHost` and `setIronPdfEnginePort` in the IronPDF settings before executing any PDF operations to route requests to the remote server.
What should you do if IronPdfEngine becomes inactive?
You can use the IronPdfEngineManager to check engine activity using `isEngineActive()`. If needed, restart the engine with `restartEngine()` to establish a fresh connection.
How can multiple application instances share a single IronPdfEngine server?
By configuring IronPdfEngine in remote mode, multiple application instances can connect to a single IronPdfEngine server over gRPC, useful in microservices and containerized deployments.
What is the importance of version matching in IronPdfEngine?
Exact version matching between IronPDF for Java and IronPdfEngine is crucial, as cross-version compatibility is not supported. Use `Settings.getIronPdfEngineVersion()` to verify compatibility.
How can you start PDF processing with IronPDF after setting up IronPdfEngine?
Once configured, you can access the full features of IronPDF in Java, such as HTML to PDF conversion, PDF editing, and more, detailed in the IronPDF Java tutorials and examples.
Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.
