ZPL how-to
Send ZPL to a Zebra printer from Node.js
A Zebra printer draws the label itself from the ZPL it receives. Your JavaScript only has to get the ZPL there as raw bytes. Node.js can do that with its standard library; a web page cannot, and needs a server or a program on the computer to do it.
What goes wrong
Anything that prints through the printer driver, as a document, renders the ZPL as text: the label comes out with the ZPL source on it, or blank. That includes window.print() in a browser. The bytes have to reach the printer unchanged, by one of the routes below.
The code needs Node.js 22 or later, and is written as ES modules: save it in .mjs files, or set "type": "module" in package.json. The label used throughout, on 4 × 2 inch stock:
^XA
^FO40,40^A0N,50,50^FDHello from Node.js^FS
^XZA network printer: port 9100
A networked Zebra printer listens on TCP port 9100 and prints whatever ZPL arrives there. Open a connection, send the bytes, close it. node:net is all it needs.
import net from 'node:net';
// Port 9100 is the printer's raw port: whatever arrives there is printed as ZPL.
export function sendZpl(host, zpl, port = 9100) {
return new Promise((resolve, reject) => {
const socket = net.connect({ host, port, timeout: 10_000 });
socket.on('timeout', () => {
socket.destroy(new Error(`No answer from ${host}:${port} within 10 seconds.`));
});
socket.on('error', reject);
// 'finish' fires once every byte has been handed to the network.
socket.on('finish', () => {
socket.destroy();
resolve();
});
socket.end(zpl, 'utf8');
});
}await sendZpl('192.168.1.50', '^XA^FO40,40^A0N,50,50^FDHello from Node.js^FS^XZ');- Use the printer's IP address or host name. Print a configuration label from the printer to find it.
- Port 9100 has to be reachable from where the code runs. A wrong address or a firewall shows up as
ECONNREFUSEDor as the 10-second timeout, not as an error from the printer. - Several labels can go in one call, one
^XA…^XZblock after another. - Port 9100 sends nothing back, so
sendZplresolving means the bytes left for the printer, not that the label printed. To check for an open head or no paper, send~HSand read the status the printer returns.
A USB printer on Windows: a printer share and copy /b
Node.js has no way to reach the Windows print spooler on its own. The route that needs no extra package is to share the printer and copy the ZPL to the share with copy /b, which sends the file byte for byte. In Windows, open the printer's properties, turn on Share this printer and give it a short share name with no spaces, such as ZD421.
import { execFile } from 'node:child_process';
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { promisify } from 'node:util';
const run = promisify(execFile);
// copy /b sends the file to the shared printer byte for byte, so the driver never renders it.
export async function sendZplWindows(share, zpl) {
// cmd.exe would run anything after an & or a | in the name, so accept only \\computer\share.
if (!/^\\\\[\w.-]+\\[\w.$-]+$/.test(share)) throw new Error(`Not a printer share: ${share}`);
const dir = await mkdtemp(join(tmpdir(), 'zpl-'));
const file = join(dir, 'label.zpl');
try {
await writeFile(file, zpl, 'utf8');
await run('cmd.exe', ['/d', '/c', 'copy', '/b', file, share]);
} finally {
await rm(dir, { recursive: true, force: true });
}
}await sendZplWindows(String.raw`\\localhost\ZD421`, zpl);- On the computer the printer is plugged into, the share is
\\localhost\ZD421; from another computer, use that computer's name in place oflocalhost.String.rawkeeps the backslashes as they are: in a plain string,\\is a single backslash. - The function refuses anything that is not a plain
\\computer\sharebefore it startscmd.exe. Without that check, a name such asZD421&whoamiwould run a second command, and the copy failing would go unnoticed. Keep the check if the share name comes from configuration or from a user. - When the copy fails, the promise rejects with the error
copyprinted, such asThe network name cannot be foundorAccess is denied. The wording varies from one machine to another. - Windows only. On Linux or macOS, send to port 9100, or set the printer up in CUPS as a raw queue so it passes the bytes through.
From the browser
A web page cannot open a raw TCP socket or reach the spooler, so neither route above works from JavaScript in the browser. Chromium browsers have WebUSB, but on Windows it needs the printer's driver replaced, so it is rarely practical. There are two usual ways round it:
- Through your server. The page sends the label's values to your own server, and the server makes the ZPL and sends it with
sendZplabove. The server has to reach the printer's port 9100, so it usually runs on the same network as the printer. - Through a program on the computer. Zebra Browser Print is a free Zebra program, installed on each computer that prints, that takes ZPL from a web page and sends it to the printers that computer can reach. Every computer that prints needs it installed. We have not tested it.
Either way, the call to zeepler belongs on the server, not in the page: the API key would be readable by anyone who opens it.
Things that trip people up
- The printer prints the ZPL as text. It is not in ZPL mode: some Zebra models also speak EPL or a line-print mode. Set the printer language to ZPL from its menu or its web page.
- Part of a value is missing. A
^or~in your data is read as a command. Printing ^, ~ and _ in ZPL shows the fix. - Accented letters print wrong. The code above sends UTF-8, which the printer only reads as UTF-8 after
^CI28. Accented characters in ZPL shows where it goes.
The same label with zeepler
Send this body to POST https://api.zeepler.com/v1/zeeplify with your API key in the x-api-key header. It is a working request, not an illustration: on every change, our tests run this same file through the API's code and compare the result with the ZPL below.
1{2 "config": {3 "size": "4x2"4 },5 "data": {6 "item": "Washer M10",7 "sku": "WS-M10-Z"8 },9 "templates": [10 {11 "type": "Text",12 "dataPath": "item",13 "coords": [40, 40],14 "font": "0,50"15 },16 {17 "type": "BarCode",18 "dataPath": "sku",19 "coords": [40, 120]20 }21 ]22}And the ZPL that comes back, ready to send to the printer:
^XA^MCY^XZ
^XA
^SZ2
^MMT
^MNY
^LL406
^PW812
^LH0,0
^CF0,50^FO40,40^FDWasher M10^FS
^BY2,2,59^FO40,120^BCN,,N,N,N,A^FDWS-M10-Z^FS
^XZInstead of building ZPL strings in JavaScript, send the values and the layout as JSON, and send whatever comes back to the printer by either route above. This is the Node.js that sent the request shown, with the built-in fetch:
// The key comes from configuration, never from source code. A missing or
// empty one fails here, not with a 401 from the API.
const API_KEY = process.env.ZEEPLER_API_KEY;
if (!API_KEY) throw new Error('Set ZEEPLER_API_KEY to your zeepler API key.');
export async function binLabel(item, sku) {
const response = await fetch('https://api.zeepler.com/v1/zeeplify', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
body: JSON.stringify({
config: { size: '4x2' },
data: { item, sku },
templates: [
{ type: 'Text', dataPath: 'item', coords: [40, 40], font: '0,50' },
{ type: 'BarCode', dataPath: 'sku', coords: [40, 120] },
],
}),
signal: AbortSignal.timeout(30_000),
});
// A 400 lists every problem field in its JSON body.
if (!response.ok) throw new Error(`zeepler answered ${response.status}: ${await response.text()}`);
return response.text();
}await sendZpl('192.168.1.50', await binLabel('Washer M10', 'WS-M10-Z'));A body the API cannot turn into a label comes back as a 400, and binLabel throws with the API's answer, which lists the problem fields. Nothing reaches the printer.
zeepler escapes ^, ~ and _ in the values for you. When a value has accented letters or any other character outside ASCII, its ZPL sets ^CI28 itself and switches back to ^CI0 at the end of the label.
Sending it
- Call the API from your own server or integration engine, not from a web page. An API key in a browser is a key anyone can copy.
- A successful call answers
200with the ZPL as plain text. A request the API cannot turn into a label answers400with every problem listed by field, and is not billed. - Send the ZPL to a Zebra or other ZPL printer at 203 dpi. At 300 dpi the same label prints at two-thirds of the size.
The API reference has every field and status code.
Related guides
- QR code size in ZPL: How ^BQ magnification sets the size of a QR code, and how to work out the size in dots.
- Printing ^, ~ and _ in ZPL: Why a caret or tilde in your data cuts the field short, and how ^FH prints them.
- Font size in ZPL: Setting text height with ^A and ^CF, converting points to dots, and why ^CF carries over.
- Send ZPL to a Zebra printer from C#: Send ZPL from .NET to a network printer on port 9100, or to a USB printer through the Windows spooler, without the driver redrawing it.
- Code 128 barcodes in ZPL: Set a Code 128 barcode's width and height with ^BY and ^BC, work out its width in dots, and pick subsets A, B and C.
- Accented characters in ZPL (^CI28): Print é, ç, ô and € with ^CI28, switch the printer back with ^CI0, and what to do on older firmware.
- Send ZPL to a Zebra printer from Python: Send ZPL from Python to a network printer on port 9100, or to a USB printer through the Windows spooler, without the driver redrawing it.
- Change a barcode to a QR code in ZPL: Swap ^BC for ^BQ, start the field data with QA, so the first characters scan, and reset the ^BY left over from the barcode.
- Label size and origin in ZPL (^PW, ^LL, ^LH): Set the label size in dots with ^PW and ^LL, move 0,0 with ^LH, and stop the last label's settings moving this one.
- Templates in ZPL: store a format with ^DF, fill it with ^XF: Store a label layout on the printer with ^DF and ^FN, fill it with ^XF, and what prints when a field or the format is missing.
- Several labels in one ZPL job: Send several different labels in one job, stop each one inheriting the last one's font and barcode settings, and number a run with ^SN and ^PQ.
- EAN-13 and Code 93 barcodes in ZPL: Print EAN-13 with ^BE and Code 93 with ^BA, and the data each one changes: a replaced check digit, and characters Code 93 cannot hold.
- Print copies of a ZPL label with ^PQ: Print several copies of one label with ^PQ, why ^PQ after ^XZ prints only one, and each serial number twice with ^SN.
- Center text in ZPL with ^FB: Center text of any length with ^FB, why centered text sits a little left, and text too long for the block.
- Center or right-align a barcode in ZPL: Right-align a barcode with the third value of ^FO, center one by working out its width, and why ^FB does not move it.
- Wrap text and new lines in ZPL: Wrap long text with ^FB, start a new line with \&, and stop ^FB writing over its last line or cutting text off.
- Rotate text and barcodes in ZPL: Turn text and barcodes with N, R, I and B, where ^FO and ^FT put a turned field, ^FW and ^POI, and why both stay set.
Help with an integration
Email info@zeepler.com. You will get a reply within 2 business days. The support policy covers response times and version changes.