ZPL2PDF - ZPL to PDF Converter

GitHub all releases

A powerful, cross-platform command-line tool that converts ZPL (Zebra Programming Language) files to high-quality PDF documents. Perfect for label printing workflows, automated document generation, and enterprise label management systems.

ZPL2PDF Demo

🚀 What's New in v3.1.1

🔧 Changed

Release tooling: Scripts under release/scripts/; Linux packaging assets under scripts/release/packages/ (documentation and contributor paths updated).
Internals: Single Labelary PDF fallback path in ConversionService across CLI, API, TCP server, and daemon; dimension/value-object consolidation and daemon PID handling without reflection.

🛠️ Maintenance

Installer pipeline: More reliable cleanup in 08-build-installer.ps1; optional cleanup-installer-output.ps1 for installer/Output.
Docker: Leaner default build context via .dockerignore.
Repo hygiene: .github/prompts/ and .github/skills/ remain untracked; the rest of .github (workflows, templates) stays versioned.

Recent highlights (v3.1.1)

--stdout, smarter default PDF naming, BinaryKits/PDFsharp bumps, dimension validation fix, Aztec ^B0 → ^BO preprocessing.
Thanks to Jacques Caruso (jacques.caruso@exhibitgroup.fr) for contributions that landed in v3.1.0.

✨ Key Features

🎯 Three Operation Modes

Conversion Mode - Convert individual files

ZPL2PDF -i label.txt -o output/ -n mylabel.pdf

Daemon Mode - Auto-monitor folders

ZPL2PDF start -l "C:\Labels"

TCP Server Mode - Virtual printer

ZPL2PDF server start --port 9101 -o output/

📐 Intelligent Dimension Handling

✅ Extract dimensions from ZPL commands (^PW, ^LL)
✅ Support for multiple units (mm, cm, inches, points)
✅ Automatic fallback to sensible defaults
✅ Priority-based dimension resolution

🌍 Multi-Language Interface

Set your preferred language:

# Temporary (current session)
ZPL2PDF status --language pt-BR

# Permanent (all sessions)
ZPL2PDF --set-language pt-BR

# Check configuration
ZPL2PDF --show-language

Supported Languages:

🇺🇸 English (en-US)
🇧🇷 Português (pt-BR)
🇪🇸 Español (es-ES)
🇫🇷 Français (fr-FR)
🇩🇪 Deutsch (de-DE)
🇮🇹 Italiano (it-IT)
🇯🇵 日本語 (ja-JP)
🇨🇳 中文 (zh-CN)

📦 Installation

Windows

Option 1: WinGet (Recommended)

winget install brunoleocam.ZPL2PDF

Option 2: Installer

Download ZPL2PDF-Setup.exe
Run installer
Choose your language during installation
Done! ✅

Linux

Ubuntu/Debian (.deb package)

# Download .deb package from releases
wget https://github.com/brunoleocam/ZPL2PDF/releases/download/v3.1.1/ZPL2PDF-v3.1.1-linux-amd64.deb

# Install package
sudo dpkg -i ZPL2PDF-v3.1.1-linux-amd64.deb

# Fix dependencies if needed
sudo apt-get install -f

# Verify installation
zpl2pdf -help

Fedora/CentOS/RHEL (.tar.gz)

# Download tarball from releases
wget https://github.com/brunoleocam/ZPL2PDF/releases/download/v3.1.1/ZPL2PDF-v3.1.1-linux-x64-rpm.tar.gz

# Extract to system
sudo tar -xzf ZPL2PDF-v3.1.1-linux-x64-rpm.tar.gz -C /

# Make executable
sudo chmod +x /usr/bin/ZPL2PDF

# Create symbolic link
sudo ln -s /usr/bin/ZPL2PDF /usr/bin/zpl2pdf

# Verify installation
zpl2pdf -help

Docker (All Linux distributions)

docker pull brunoleocam/zpl2pdf:latest
docker run -v ./watch:/app/watch -v ./output:/app/output brunoleocam/zpl2pdf:latest

macOS

Intel Macs

# Download
curl -L https://github.com/brunoleocam/ZPL2PDF/releases/download/v3.1.1/ZPL2PDF-v3.1.1-osx-x64.tar.gz -o zpl2pdf.tar.gz

# Extract and run
tar -xzf zpl2pdf.tar.gz
./ZPL2PDF -help

Apple Silicon (M1/M2/M3)

curl -L https://github.com/brunoleocam/ZPL2PDF/releases/download/v3.1.1/ZPL2PDF-v3.1.1-osx-arm64.tar.gz -o zpl2pdf.tar.gz
tar -xzf zpl2pdf.tar.gz
./ZPL2PDF -help

🚀 Quick Start

Convert a Single File

ZPL2PDF -i label.txt -o output_folder -n my_label.pdf

Convert with Custom Dimensions

ZPL2PDF -i label.txt -o output_folder -w 10 -h 5 -u cm

Convert ZPL String Directly

ZPL2PDF -z "^XA^FO50,50^A0N,50,50^FDHello World^FS^XZ" -o output_folder

Start Daemon Mode (Auto-Conversion)

# Start with default settings
ZPL2PDF start

# Start with custom folder
ZPL2PDF start -l "C:\Labels" -w 7.5 -h 15 -u in

# Check status
ZPL2PDF status

# Stop daemon
ZPL2PDF stop

📖 Usage Guide

Conversion Mode Parameters

ZPL2PDF -i <input_file> (-o <output_folder> | --stdout) [options]
ZPL2PDF -z <zpl_content> (-o <output_folder> | --stdout) [options]

| Parameter | Description | Example | |-----------|-------------|---------| | -i <file> | Input ZPL file (.txt, .prn, .zpl, .imp) | -i label.zpl | | -z <content> | ZPL content as string | -z "^XA...^XZ" | | -o <folder> | Output folder for PDF (required unless --stdout) | -o C:\Output | | --stdout | Write PDF bytes to stdout only (no file) | --stdout | | -n <name> | Output PDF filename (optional; default: input basename or timestamp for -z) | -n result.pdf | | -w <width> | Label width | -w 10 | | -h <height> | Label height | -h 5 | | -u <unit> | Unit (mm, cm, in) | -u cm | | -d <dpi> | Print density (default: 203) | -d 300 | | --renderer | Rendering engine (offline/labelary/auto) | --renderer labelary | | --fonts-dir | Custom fonts directory | --fonts-dir C:\Fonts | | --font | Map specific font | --font "A=arial.ttf" |

Custom fonts (offline renderer): ZPL font IDs (^A0N, ^AAN, ^ABN, …) are mapped to TTF/OTF files. Use --font "A=arial.ttf" to map font A; use multiple --font for B, 0, etc. If you set --fonts-dir ./fonts, relative paths in --font are resolved under that directory (e.g. --font "A=arial.ttf" → ./fonts/arial.ttf). Example:

ZPL2PDF -i zpl_teste.txt -o output -n label1.pdf -d 600 -w 10.0 -h 8.0 -u cm --fonts-dir ./fonts --font "A=arial.ttf" --font "B=another.ttf"

Daemon Mode Commands

ZPL2PDF start [options]    # Start daemon in background
ZPL2PDF stop               # Stop daemon
ZPL2PDF status             # Check daemon status
ZPL2PDF run [options]      # Run daemon in foreground (testing)

| Option | Description | Default | |--------|-------------|---------| | -l <folder> | Folder to monitor | Documents/ZPL2PDF Auto Converter | | -w <width> | Fixed width for all conversions | Extract from ZPL | | -h <height> | Fixed height for all conversions | Extract from ZPL | | -u <unit> | Unit of measurement | mm | | -d <dpi> | Print density | 203 |

TCP Server Commands

ZPL2PDF server start [options]    # Start TCP server (virtual printer)
ZPL2PDF server stop               # Stop TCP server
ZPL2PDF server status             # Check TCP server status

| Option | Description | Default | |--------|-------------|---------| | --port <port> | TCP port to listen on | 9101 | | -o <folder> | Output folder for PDFs | Documents/ZPL2PDF TCP Output | | --foreground | Run in foreground (not background) | Background | | --renderer | Rendering engine | offline |

Language Commands

--language <code>           # Temporary language override
--set-language <code>       # Set language permanently
--reset-language            # Reset to system default
--show-language             # Show current configuration

🎨 Rendering Engines

Offline (BinaryKits) - Default

ZPL2PDF -i label.txt -o output/ --renderer offline

✅ Works without internet
✅ Fast processing
⚠️ Some ZPL commands may render differently

Labelary (API) - High Fidelity

ZPL2PDF -i label.txt -o output/ --renderer labelary

✅ Exact Zebra printer emulation
✅ High-fidelity rendering via Labelary (uses Labelary to generate PNGs)
✅ Works for multi-label ZPL inputs
⚠️ Requires internet connection

Auto (Fallback)

ZPL2PDF -i label.txt -o output/ --renderer auto

✅ Tries Labelary first
✅ Falls back to BinaryKits if offline

🌐 REST API

Start the API server:

ZPL2PDF --api --host localhost --port 5000

Health check

curl -s http://localhost:5000/api/health

{
  "status": "ok",
  "service": "ZPL2PDF API"
}

Convert (ZPL to PDF/PNG)

Endpoint: POST /api/convert

Request body

{
  "zpl": "^XA...^XZ",
  "zplArray": ["^XA...^XZ"],
  "format": "pdf",
  "width": 7.5,
  "height": 15,
  "unit": "in",
  "dpi": 203,
  "renderer":

ZPL2PDF

Install / Use

README