English | Português-BR | Español | Français | Deutsch | Italiano | 日本語 | 中文

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.

• Fixed Issue #45: Duplicate or blank labels when ^XA appears inside ~DGR: base64 payload — ^XA is now treated as label start only at line start or after ^XZ.

• Issue #48 – TCP Server: Virtual Zebra printer mode is now implemented. Use ZPL2PDF server start --port 9101 -o output/, server stop, and server status.
• REST API (PR #47): Run ZPL2PDF --api --host localhost --port 5000 for POST /api/convert (ZPL to PDF or PNG) and GET /api/health.

• Fixed Issue #39: Sequential graphic processing for multiple graphics with same name
  • ZPL files with multiple ~DGR graphics now process correctly
  • Each label uses the correct graphic based on sequential state
  • ^IDR cleanup commands no longer generate blank pages
  • Resolves issue where all labels were identical in Shopee shipping label files

• Added input validation in public methods
• Improved exception handling
• Performance optimizations with compiled regex
• Code cleanup and removal of unused methods

• 🎨 Labelary API Integration - High-fidelity ZPL rendering with vector PDF output
• 🖨️ TCP Server Mode - Virtual Zebra printer on TCP port (default: 9101)
• 🔤 Custom Fonts - Load TrueType/OpenType fonts with --fonts-dir and --font
• 📁 Extended File Support - Added .zpl and .imp file extensions
• 📝 Custom Naming - Set output filename via ^FX FileName: in ZPL

--renderer offline    # BinaryKits (default, works offline)
--renderer labelary   # Labelary API (high-fidelity, requires internet)
--renderer auto       # Try Labelary, fallback to BinaryKits

ZPL2PDF server start --port 9101 -o output/
ZPL2PDF server status
ZPL2PDF server stop

• 🌍 Multi-language Support - 8 languages (EN, PT, ES, FR, DE, IT, JA, ZH)
• 🔄 Daemon Mode - Automatic folder monitoring and batch conversion
• 🏗️ Clean Architecture - Completely refactored with SOLID principles
• 🌍 Cross-Platform - Native support for Windows, Linux, and macOS
• 📐 Smart Dimensions - Automatic ZPL dimension extraction (^PW, ^LL)
• ⚡ High Performance - Async processing with retry mechanisms
• 🐳 Docker Support - Alpine Linux optimized (470MB)
• 📦 Professional Installer - Windows installer with multi-language setup

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

ZPL2PDF start -l "C:\Labels"

ZPL2PDF server start --port 9101 -o output/

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

Set your preferred language:

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

# 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)

winget install brunoleocam.ZPL2PDF

1. Download ZPL2PDF-Setup-2.0.1.exe
2. Run installer
3. Choose your language during installation
4. Done! ✅

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

# Install package
sudo dpkg -i ZPL2PDF-v2.0.1-linux-amd64.deb

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

# Verify installation
zpl2pdf --help

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

# Extract to system
sudo tar -xzf ZPL2PDF-v2.0.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 pull brunoleocam/zpl2pdf:latest
docker run -v ./watch:/app/watch -v ./output:/app/output brunoleocam/zpl2pdf:latest

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

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

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

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

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

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

# 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

ZPL2PDF -i <input_file> -o <output_folder> [options]
ZPL2PDF -z <zpl_content> -o <output_folder> [options]

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

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

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

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

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

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

• ✅ Exact Zebra printer emulation
• ✅ Vector PDF output (smaller files)
• ✅ Automatic batching for 50+ labels
• ⚠️ Requires internet connection

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

• ✅ Tries Labelary first
• ✅ Falls back to BinaryKits if offline

# Pull image
docker pull brunoleocam/zpl2pdf:latest

# Run daemon mode
docker run -d \
  --name zpl2pdf \
  -v ./watch:/app/watch \
  -v ./output:/app/output \
  -e ZPL2PDF_LANGUAGE=en-US \
  brunoleocam/zpl2pdf:latest

Create docker-compose.yml:

version: '3.8'

services:
  zpl2pdf:
    image: brunoleocam/zpl2pdf:latest
    container_name: zpl2pdf-daemon
    volumes:
      - ./watch:/app/watch
      - ./output:/app/output
    environment:
      - ZPL2PDF_LANGUAGE=pt-BR
    restart: unless-stopped

Run:

docker-compose up -d

📘 Full Docker Guide: docs/DOCKER_GUIDE.md

Create a zpl2pdf.json file in the application directory:

{
  "language": "en-US",
  "defaultWatchFolder": "C:\\Users\\user\\Documents\\ZPL2PDF Auto Converter",
  "labelWidth": 10,
  "labelHeight": 5,
  "unit": "cm",
  "dpi": 203,
  "logLevel": "Info",
  "retryDelay": 2000,
  "maxRetries": 3
}

See zpl2pdf.json.example for full configuration options.

📘 Language Configuration Guide: docs/LANGUAGE_CONFIGURATION.md

• ✅ ^XA / ^XZ - Label start/end
• ✅ ^PW<width> - Print width in points
• ✅ ^LL<length> - Label length in points
• ✅ All standard ZPL text, graphics, and barcode commands

ZPL2PDF automatically extracts dimensions:

^XA
^PW800        ← Width: 800 points
^LL1200       ← Height: 1200 points
^FO50,50^A0N,50,50^FDHello^FS
^XZ

Conversion: mm = (points / 203) * 25.4

1. ⭐ Explicit Parameters (-w, -h) - Highest priority
2. ⭐⭐ ZPL Commands (^PW, ^LL) - If no parameters
3. ⭐⭐⭐ Default Values (100mm × 150mm) - Fallback

ZPL2PDF follows Clean Architecture principles:

src/
├── Application/          # Use Cases & Services
│   ├── Services/         # Business logic
│   └── Interfaces/       # Service contracts
├── Domain/              # Business entities & rules
│   ├── ValueObjects/    # Immutable data objects
│   └── Services/        # Domain interfaces
├── Infrastructure/      # External concerns
│   ├── FileSystem/      # File operations
│   ├── Rendering/       # PDF generation
│   └── Processing/      # Queue management
├── Presentation/        # CLI & user interface
│   └── Handlers/        # Mode handlers
└── Shared/             # Common utilities
    ├── Localization/   # Multi-language
    └── Constants/      # Configuration

# All tests
dotnet test

# Unit tests only
dotnet test tests/ZPL2PDF.Unit/

# Integration tests
dotnet test tests/ZPL2PDF.Integration/

# With coverage
dotnet test --collect:"XPlat Code Coverage"

• ✅ Unit Tests: 90%+ coverage
• ✅ Integration Tests: End-to-end workflows
• ✅ Cross-Platform: Windows, Linux, macOS

• 📖 Complete Documentation - Full user manual
• 🌍 Multi-language Configuration
• 🐳 Docker Usage Guide
• 📦 Inno Setup Guide

• 🛠️ Contributing Guide
• 📋 Changelog
• 🏗️ Architecture Overview
• 🔄 CI/CD Workflow

• 🔨 Build Scripts
• 🐳 Docker Publishing
• 📦 Windows Installer

// C# example
Process.Start("ZPL2PDF.exe", "-i label.txt -o output/ -w 10 -h 5 -u cm");

# Process all ZPL files in a folder
for file in *.txt; do
    ZPL2PDF -i "$file" -o output/
done

# Start daemon on system startup
ZPL2PDF start -l "C:\Labels\Incoming"

# Deploy to server
docker run -d \
  -v /srv/labels:/app/watch \
  -v /srv/pdfs:/app/output \
  --restart always \
  brunoleocam/zpl2pdf:latest

• ✅ Async processing with configurable concurrency
• ✅ Retry mechanisms for locked files
• ✅ Memory-efficient image processing
• ✅ Optimized PDF generation with compression

• .NET 9.0 SDK or later
• Git
• Visual Studio 2022 or VS Code
• Docker (for cross-platform testing)

# Clone repository
git clone https://github.com/brunoleocam/ZPL2PDF.git
cd ZPL2PDF

# Restore dependencies
dotnet restore

# Build solution
dotnet build

# Run tests
dotnet test

# Build for your platform
dotnet publish -c Release -r win-x64 --self-contained true

# Build all platforms
.\scripts\build-all-platforms.ps1  # Windows
./scripts/build-all-platforms.sh   # Linux/macOS

ZPL2PDF/
├── src/                    # Source code (Clean Architecture)
├── tests/                  # Unit & integration tests
├── docs/                   # Documentation
│   ├── i18n/              # Translated documentation
│   ├── Image/             # Screenshots & icons
│   └── Sample/            # Sample ZPL files
├── installer/              # Windows installer (Inno Setup)
├── scripts/                # Build & release scripts
├── .github/workflows/      # GitHub Actions CI/CD
├── docker-compose.yml      # Docker orchestration
└── Dockerfile              # Docker image definition

# Enable verbose logging
ZPL2PDF -i label.txt -o output/ --log-level Debug

• 📖 Wiki
• 🐛 Issues
• 💬 Discussions

We welcome contributions! See CONTRIBUTING.md for details.

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/ZPL2PDF.git

# 2. Create feature branch
git checkout -b feature/amazing-feature

# 3. Make changes and test
dotnet test

# 4. Commit and push
git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature

# 5. Create Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

Built with amazing open-source libraries:

• BinaryKits.Zpl - ZPL parsing and rendering
• PdfSharpCore - PDF generation
• SkiaSharp - Cross-platform graphics

• 📖 Documentation: Full documentation
• 🐛 Bug Reports: GitHub Issues
• 💬 Questions: GitHub Discussions
• 📧 Email: Contact

If ZPL2PDF helps you, consider supporting its development:

• ☕ Buy Me a Coffee
• 🎗️ Patreon
• 💖 GitHub Sponsors

Your support helps maintain and improve ZPL2PDF for everyone!

If ZPL2PDF helps you, please ⭐ star the repository!

Thanks to all contributors who have helped make ZPL2PDF better!

Image may be cached; see full list on GitHub.

ZPL2PDF - Convert ZPL labels to PDF easily and efficiently.