← All guides

How to convert PDF to ZPL

You have a PDF — usually a carrier shipping label from UPS, FedEx, USPS, Endicia or EasyPost — and a Zebra thermal printer that only speaks ZPL. Here are three ways to convert it, fastest first:

1. Free online converter — drop the PDF, get ZPL per page with a pixel-true preview. No signup.
2. Open-source PHP library — benfaerber/pdf-to-zpl, 26,000+ installs, runs inside your own app.
3. REST API — one curl (or a PHP/Python/C#/Java SDK call) from any stack, shown below.

An 8-page PDF converted by this engine and printed on a real Zebra — each page one label.

What a PDF→ZPL conversion actually does

ZPL has no PDF support. The conversion rasterizes each PDF page at the printer's exact density, converts the pixels to a 1-bit bitmap, and wraps it in a ^GFA (Graphic Field) command with Zebra's ACS run-length compression:

^XA
^GFA,121836,121836,102,,:::::N03FE,M01JF8...
^XZ

That blob is the label. Send it to the printer over TCP port 9100 and it prints — no drivers, no middleware:

cat label.zpl | nc 192.168.1.50 9100

The mistake that ruins most conversions: density

Zebra printers come in four densities, and ZPL coordinates are physical dots, so a label converted for the wrong density prints at the wrong size:

| Printer density | Dots/mm | DPI | 4×6" label is | |---|---|---|---| | 6 dpmm | 6 | 152 | 609 × 914 dots | | 8 dpmm (most common) | 8 | 203 | 812 × 1218 dots | | 12 dpmm | 12 | 300 | 1218 × 1828 dots | | 24 dpmm | 24 | 600 | 2436 × 3656 dots |

If your 4×6 label prints as a small rectangle in the corner, it was converted at 8 dpmm and printed on a 12 dpmm printer (or vice versa, cropped). Convert at the density of the target printer — don't rescale afterward, which blurs barcode edges.

Converting via the API

curl https://api.stripyhorse.io/v1/convert \
  -H "X-Api-Key: sh_live_YOUR_KEY" \
  -F file=@shipping-label.pdf -F preset=4x6 -F dpmm=8

Each page comes back as its own ZPL string. There is also a bulk endpoint that accepts up to 20 files and streams results per page as they finish — useful for end-of-day batch processing.

Will the barcodes still scan?

Yes, if two things are true:

1. Rasterize at final size in one pass. Rendering a PDF large and then shrinking it resamples the barcode's bars into gray edges, and the 1-bit threshold then rounds bar widths inconsistently. Scanners tolerate some of this; at small module widths they stop. A correct converter renders the PDF directly at the target pixel size.
2. The source PDF's barcode has enough resolution for your density. A barcode that's crisp at 300 dpi can alias at 152 dpi. When in doubt, print one and scan it — or use a converter that re-renders detected barcodes as native ZPL fields (^BC) at printhead precision instead of rasterizing them.

Our engine is cross-validated against thousands of physically printed and scanned carrier labels — the same pipeline as the open-source library, rewritten in Go and roughly 100× faster (~45 ms per page).

FAQ

Can I convert PDF to ZPL for free?

Yes — the online converter is free without signup, and the PHP library is MIT-licensed.

Does the output work on any Zebra printer?

^GFA graphics print on every ZPL-II printer (ZD, ZT, GX, GK, 105SL…), and on most Zebra-compatible printers from Honeywell/Datamax with ZSim enabled. Match the dpmm.

How do I convert multi-page PDFs?

Each PDF page becomes one label. The API returns them in order; the bulk endpoint streams {"file":…,"page":…,"zpl":…} objects as pages finish.

PNG or JPG instead of PDF?

Same pipeline: the image converter accepts PNG, GIF and JPEG.

Published 2026-08-24 · Ben Faerber — software engineer, five years building warehouse fulfillment and label-printing systems; maintainer of pdf-to-zpl (26,000+ installs powering production label generation).