ZPLPrinter Web API for Docker

Convert, Preview & Render ZPL commands to PNG, JPG & PDF from Docker!

ZPLPrinter Web API for Docker allows you to Convert, Preview and Render raw ZPL (Zebra Programming Language) commands to well known image and document formats like PNG, JPG, PDF, TIFF, PCX, Zebra GRF ASCII hex, Zebra EPL Binary Graphic, Honeywell-Intermec FingerPrint Binary Graphic, EPSON ESC/POS NV Binary Graphic & HP PCL Binary Graphic from Any Development Platform and Programming Languages (.NET, Java, PHP, Javascript, Python, Ruby, and more!) with a single HTTP POST.

It ships as a Linux Docker image for amd64 and arm64 that you run on your own servers, Kubernetes cluster or cloud account. Your ZPL and label data never leave your infrastructure. If you prefer an in-process library for .NET, see the ZPLPrinter Emulator SDK for .NET.

Features at a Glance

Overview

Designed by following some of the REST principles, ZPLPrinter Web API for Docker responds to a simple HTTP POST by specifying the ZPL commands and printer settings through a JSON object in the request body, returning the output rendering in the image or document format specified through the Accept header.

Help Doc Topics

Download and run ZPLPrinter Web API for Docker

ZPLPrinter Web API for Docker is available at Docker Hub registry.

• To pull/download the Docker image, please type the following from a Terminal:

  AMD
  docker pull neodynamic/zplprinterwebapi:7.0.1
  ARM
  docker pull neodynamic/zplprinterwebapi:7.0.1-arm64

• To run the Docker image, please type the following from a Terminal:

  AMD
  docker run -it --rm -p 8080:8080 neodynamic/zplprinterwebapi:7.0.1
  ARM
  docker run -it --rm -p 8080:8080 neodynamic/zplprinterwebapi:7.0.1-arm64
   License Registration    Evaluation Mode Limitations    Change Log
  
  

  Special Parameters

  • Auto HTTPS Redirection: By default, HTTPS redirection is enabled. It can be disabled by specifying the following parameter -e "USE_HTTPS_REDIRECTION=false"
  • Swagger UI: By default, Swagger UI is enabled. It can be disabled by specifying the following parameter -e "SWAGGER_UI_ENABLED=false"

Run ZPLPrinter WebAPI on a Custom Port

By default, our Docker image exposes port 8080 only. If you want to expose and use another different port, then do the following.

1. Let's suppose you want to use port 12345, then run the docker image with the following parameters:
   
   
   AMD

   docker run -it --rm -p 8080:12345 neodynamic/zplprinterwebapi:7.0.1 -e ASPNETCORE_HTTP_PORTS=12345

   ARM

   docker run -it --rm -p 8080:12345 neodynamic/zplprinterwebapi:7.0.1-arm64 -e ASPNETCORE_HTTP_PORTS=12345
2. Special case for port 80: If you need to use port 80, then run the docker image with the following parameters:
   
   
   AMD

   docker run -it --rm -p 8080:80 neodynamic/zplprinterwebapi:7.0.1 -u root -e ASPNETCORE_HTTP_PORTS=80

   ARM

   docker run -it --rm -p 8080:80 neodynamic/zplprinterwebapi:7.0.1-arm64 -u root -e ASPNETCORE_HTTP_PORTS=80

How To Use It - Basic Sample

The following source code invokes the ZPLPrinter Web API for Docker to generate a PNG image for the specified ZPL Commands. For more advanced settings please refer to the ZPLPrintJob JSON Object

•   CURL
•   PHP
•   RUBY
•   PYTHON
•   PERL
•   JAVA
•   C#
•   JS/XHR
•   NODE

                    
curl -X POST "http://localhost:8080/ZPLPrinter" \
     -H  "Accept: image/png" \
     -H  "Content-Type: application/json" \
     -d "{\"zplCommands\":\"^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ\"}" \
     --output label.png
                        
                

                    
$data = array(
  'zplCommands' => '^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ'
);

$options = array(
  'http' => array(
    'method'  => 'POST',
    'content' => json_encode( $data ),
    'header' =>  "Content-Type: application/json\r\n" .
                "Accept: image/png\r\n"
    )
);

$context  = stream_context_create( $options );
$url = 'http://localhost:8080/ZPLPrinter';
$response = file_get_contents( $url, false, $context );
file_put_contents('label.png', $response);
                        
                

                    
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://localhost:8080/ZPLPrinter")

header = {'Accept':'image/png', 'Content-Type': 'application/json'}

data = {zplCommands: '^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ'}

http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = data.to_json

response = http.request(request)

open('/tmp/label.png', 'wb' ) { |file|
    file.write(response.body)
}
                        
                

                    
import requests
import json

url = "http://localhost:8080/ZPLPrinter"

jsondata = json.dumps( {"zplCommands": "^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ"} )

headers = {
    'content-type': "application/json",
    'accept': "image/png"
    }

response = requests.request("POST", url, data=jsondata, headers=headers)

if response.status_code == 200:
    with open("label.png", 'wb') as f:
        f.write(response.content)

                        
                

                    
use LWP::UserAgent;
my $ua = LWP::UserAgent->new;
my $server_endpoint = "http://localhost:8080/ZPLPrinter";
my $req = HTTP::Request->new(POST => $server_endpoint);
$req->header('content-type' => 'application/json');
$req->header('accept' => 'image/png');

my $post_data = '{ "zplCommands" : "^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ" }';

$req->content($post_data);

my $resp = $ua->request($req);
open FILEHANDLE, ">label.png";
print FILEHANDLE $resp->{_content};
close FILEHANDLE;
                        
                

                    
CloseableHttpClient client = HttpClients.createDefault();
HttpPost httpPost = new HttpPost("http://localhost:8080/ZPLPrinter");
 
String json = "{\"zplCommands\" : \"^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ\"}";
StringEntity body = new StringEntity(json);
httpPost.setEntity(body);
httpPost.setHeader("Accept", "image/png");
httpPost.setHeader("Content-type", "application/json");
 
CloseableHttpResponse response = client.execute(httpPost);
HttpEntity result = response.getEntity();
if (result != null) {
    try (FileOutputStream outstream = new FileOutputStream(new File("label.png"))) {
        result.writeTo(outstream);
    }
}
client.close();     
                        
                

                    
using var http = new HttpClient();

var json = "{\"zplCommands\":\"^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ\"}";
var request = new HttpRequestMessage(HttpMethod.Post, "http://localhost:8080/ZPLPrinter")
{
    Content = new StringContent(json, Encoding.UTF8, "application/json")
};
request.Headers.Accept.ParseAdd("image/png");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync("label.png", await response.Content.ReadAsByteArrayAsync());
                        
                

                    
// Browser (inside a <script type="module">): render the label in an img element
const response = await fetch("http://localhost:8080/ZPLPrinter", {
    method: "POST",
    headers: { "Content-Type": "application/json", "Accept": "image/png" },
    body: JSON.stringify({
        zplCommands: "^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ"
    })
});
const blob = await response.blob();
document.getElementById("label").src = URL.createObjectURL(blob);
                        
                

                    
// Node.js 18+ (built-in fetch). Save as convert.mjs (ES module, top-level await)
import fs from "fs";

const response = await fetch("http://localhost:8080/ZPLPrinter", {
    method: "POST",
    headers: { "Content-Type": "application/json", "Accept": "image/png" },
    body: JSON.stringify({
        zplCommands: "^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ"
    })
});
fs.writeFileSync("label.png", Buffer.from(await response.arrayBuffer()));
                        
                

The Accept Header

The desired output rendering format must be specified through the Accept header. The supported formats are the following:

Web API Doc

Interactive OpenAPI reference. The same swagger.json is used by the Swagger UI built into the container (enabled by default). All request properties are also listed in The ZPLPrintJob Object.

The ZPLPrintJob Object

The ZPLPrintJob is the JSON Object sent in the body of POST /ZPLPrinter. It specifies the ZPL commands (the only required property) and the printer settings like DPI, label size, colors, background and watermark images, paper size and format options.

{
  "zplCommands": "^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ",
  "dpi": 203,
  "labelWidthInchUnit": 4,
  "labelHeightInchUnit": 6,
  "renderOutputRotation": 0,
  "paperWidth": 8.5,
  "paperHeight": 11,
  "paperOrientation": "Portrait"
}

Errors

Successful requests return HTTP 200 with the output in the format requested by the Accept header. If an error occurs while processing the ZPLPrintJob, the API returns HTTP 500 with a ProblemDetails JSON object:

{
  "type": "string",
  "title": "string",
  "status": 500,
  "detail": "string",
  "instance": "string"
}

If you get this error with valid ZPL, please contact our support team.

ZPL Commands Support

ZPLPrinter Web API for Docker supports most of the ZPL formatting and control commands. The following table lists the supported commands as well as the ones which are under work. Not listed or unsupported commands will be skipped in the parsing stage.

Licensing

On-Premise - Full Deployment Control

ZPLPrinter Web API is licensed for Private On-Premise environments giving you full control on the infrastructure where our product will run on. Please refer to Licensing model and prices...

 License Registration

When you buy a commercial license of ZPLPrinter Web API for Docker, you are provided with license information (LicenseOwner & LicenseKey) to register the product. The license information must be specified to the Docker image as environment variables as follows:

Which ZPL Edition Do I Need?

The same ZPL rendering engine is available in four editions:

ZPLPrinter Web API FAQ

How do I convert ZPL to PDF with a REST API?

Run the container with docker run -p 8080:8080 neodynamic/zplprinterwebapi:7.0.1, then POST a JSON body like {"zplCommands":"^XA...^XZ"} to http://localhost:8080/ZPLPrinter with the header Accept: application/pdf. The response is the PDF, with one page per label.

Is it a self-hosted alternative to online ZPL viewer APIs?

Yes. ZPLPrinter Web API runs as a Docker container on your own servers or cloud account, so labels with customer or shipping data never leave your infrastructure and there is no dependency on an external web service.

Which programming languages can I use?

Any language that can send an HTTP POST with JSON: Python, Node.js, JavaScript, Java, PHP, C#, Ruby, Perl, Go or curl. There is no SDK to install.

Which output formats are supported?

PNG, JPG, PDF, TIFF and PCX, plus printer formats: Zebra GRF ASCII hex, Zebra EPL binary graphic, Honeywell-Intermec FingerPrint, EPSON ESC/POS NV and HP PCL. The format is chosen with the Accept header.

How are multiple labels returned?

PDF and TIFF return all labels in one multipage file. For PNG, JPG, PCX and the printer formats, use the +json Accept variant to get a JSON array of Base64 data URIs, or the +zip variant to get a ZIP with one file per label. The plain variant returns only the first label.

Does it run on ARM64?

Yes. Images are published for amd64 (neodynamic/zplprinterwebapi:7.0.1) and arm64 (neodynamic/zplprinterwebapi:7.0.1-arm64), so it runs on ARM servers, AWS Graviton and Raspberry Pi class devices.

Which DPI values are supported?

152 (6 dpmm), 203 (8 dpmm), 300 (12 dpmm) and 600 (24 dpmm). The dpi value must match the resolution the ZPL was designed for, otherwise the label will look scaled.

Can I convert ZPL for printers that do not support ZPL?

Yes. Request EPL, FingerPrint, ESC/POS NV or HP PCL output and set enablePrinting to true so the output is formatted for printing, then send the returned bytes to the printer.

What are the limitations of the evaluation version?

The trial is fully functional and does not expire, but it adds a TRIAL stamp to the output and replaces characters above byte value 127 with an X when resident fonts are used. See Evaluation Mode.

 Latest Release: v7.0.1 2026-11-03

• Fixed! Font scaling.
• Fixed! Text elements size and position when using custom fonts.

Full change log (all versions since v1.0) →