How to Connect to a Remote IronPdfEngine from Python

When Should You Use Remote IronPdfEngine?

The default local mode covers the majority of Python PDF use cases. A remote IronPdfEngine setup is worth considering in specific architectural scenarios.

High-traffic, shared PDF services are the most common reason. When several microservices or background workers all need to generate PDFs, spinning up a single IronPdfEngine instance and routing all requests through it keeps resource consumption predictable and eliminates the overhead of loading the engine in each separate process.

Containerized deployments also benefit from the separation. In a Docker or Kubernetes environment, isolating the PDF workload into its own container gives you independent scaling: you can scale the rendering service without touching your application tier. The IronPdfEngine container exposes a gRPC port, and each application container sends rendering requests over the internal network.

Separating the PDF workload from the main application process matters when rendering is CPU- or memory-intensive. Offloading that work to a dedicated engine container prevents the main process from being blocked during large document operations, and it simplifies performance monitoring since the engine's resource consumption is isolated.

For projects where none of these apply — single-process scripts, small-volume automations, or local development work — the default mode is simpler and equally capable.

How Do You Install IronPDF for Python?

Installing IronPDF for Python requires pip and an active Python environment. The package is distributed through PyPI.

//:path=shell
pip install ironpdf

//:path=shell
pip install ironpdf

No additional engine download is required for local usage. When you install the package, the engine components are included automatically. For remote mode, the engine runs separately (see the pull-and-run guide linked below) and your application connects to it over gRPC.

How Do You Configure the Remote Connection?

Configuring the remote connection requires one import and one method call. The IronPdfConnectionConfiguration.RemoteServer() method accepts a host-and-port string in the format "host:port".

//:path=use-ironpdfengine-configure.py
from ironpdf import Installation, IronPdf

# Configure the connection to a remote IronPdfEngine instance
# Replace with your server's actual address and port
Installation.ConnectToIronPdfHost(
    IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer("123.456.7.8:33350")
)

//:path=use-ironpdfengine-configure.py
from ironpdf import Installation, IronPdf

# Configure the connection to a remote IronPdfEngine instance
# Replace with your server's actual address and port
Installation.ConnectToIronPdfHost(
    IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer("123.456.7.8:33350")
)

Place this configuration block at the entry point of your application — for example, at the top of your main.py or inside your application startup handler — before any call that creates or reads a PDF document. All subsequent IronPDF operations in that process will route through the remote engine without any additional configuration per call.

How Do You Verify the Remote Connection Is Working?

After calling ConnectToIronPdfHost, run a minimal rendering test to confirm the remote engine is responding correctly. The example below renders a short HTML string and saves it to disk.

//:path=use-ironpdfengine-verify.py
from ironpdf import Installation, IronPdf, ChromePdfRenderer

# Configure the remote connection
Installation.ConnectToIronPdfHost(
    IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer("123.456.7.8:33350")
)

# Render a simple HTML string to verify the engine is connected
renderer = ChromePdfRenderer()
pdf = renderer.RenderHtmlAsPdf("<h1>Connection verified</h1>")
pdf.SaveAs("output/connection-test.pdf")

//:path=use-ironpdfengine-verify.py
from ironpdf import Installation, IronPdf, ChromePdfRenderer

# Configure the remote connection
Installation.ConnectToIronPdfHost(
    IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer("123.456.7.8:33350")
)

# Render a simple HTML string to verify the engine is connected
renderer = ChromePdfRenderer()
pdf = renderer.RenderHtmlAsPdf("<h1>Connection verified</h1>")
pdf.SaveAs("output/connection-test.pdf")

If the rendering completes without error and connection-test.pdf is created, the remote engine is connected and operational. If the call throws a connection error, verify the host address, check that port 33350 (or your configured port) is open, and confirm the IronPdfEngine Docker container is running.

What Are the Next Steps?

This guide covered how to connect IronPDF for Python to a remote IronPdfEngine instance, including when to use remote mode, how to install the package, and how to configure and verify the gRPC connection.

To put the connected engine to work, explore these resources:

• How to Pull and Run IronPdfEngine — step-by-step instructions for starting the IronPdfEngine Docker container
• Generate PDFs from HTML in Python — use the connected engine to render HTML documents
• Edit Existing PDFs in Python — add annotations, merge documents, and apply stamps
• IronPDF for Python Overview — full getting-started guide with install instructions and first examples

To get started with a free trial license, no credit card is required. For production deployments, view licensing options including team and OEM packages.