How a ZPL label is structured
A ZPL label is plain text. It starts with ^XA and ends with ^XZ. Between the two, each field is placed with
^FO (field origin), described by a formatting command (font, barcode…), filled with ^FD (field data) and closed with
^FS (field separator).
^XA
^FO50,50^A0N,40,40^FDHello world^FS
^XZ
Commands that start with a caret ^ are format commands; commands that start with a tilde ~ are control commands that act
immediately (for example ~JC to calibrate the media). ZPL is not case-sensitive for command names, but field data is printed as sent.
Units: dots, not millimetres
All positions and sizes are expressed in dots, so the same coordinates print at different physical sizes on printers with different resolutions.
| Resolution | Dots per mm | 10 mm = |
|---|---|---|
| 203 dpi | 8 | 80 dots |
| 300 dpi | 11.8 | 118 dots |
| 600 dpi | 23.6 | 236 dots |
Set the printable width with ^PW and the label length with ^LL, both in dots. On a 100 × 60 mm label at 203 dpi:
^PW800 and ^LL480.
Text: ^A, ^CF and ^FB
^A0N,h,wselects the scalable font 0 in normal orientation (N), with heighthand widthwin dots. Other orientations:R(90°),I(180°),B(270°).^CF0,30sets a default font for the following fields.^FBwidth,lines,spacing,justificationcreates a text block that wraps:^FB600,3,0,Lwraps over at most 3 lines in 600 dots, left-aligned (Ccentred,Rright,Jjustified).
^XA
^CI28
^FO40,40^A0N,36,36^FDCrème brûlée — lot A12^FS
^FO40,100^A0N,24,24^FB700,3,0,L^FDA long description that wraps automatically inside a 700-dot block.^FS
^XZ
Accents and non-Latin characters: ^CI28 declares the field data as UTF-8. Without it, characters such as é, ü or ç
may print incorrectly.
Barcodes: Code 128, QR and DataMatrix
^BY sets the module width (narrowest bar, in dots) and the default barcode height. Then the barcode command describes the symbology:
- Code 128:
^BCN,h,Y,N,N— orientation, height, human-readable text below (Y), text above (N), check digit (N). - QR Code:
^BQN,2,m— model 2, magnificationm. The data starts with an error-correction level and an input mode, for example^FDQA,https://example.com^FS(Q = quartile error correction, A = automatic input). - DataMatrix:
^BXN,h,200— module sizehin dots, quality 200 (ECC 200).
^XA
^BY3,3,100
^FO40,40^BCN,100,Y,N,N^FD4005-88120^FS
^FO40,200^BQN,2,6^FDQA,https://labelcross.com^FS
^FO400,200^BXN,8,200^FDLOT-2611^FS
^XZ
For GS1-128 (shipping and SSCC labels), the barcode must start with the FNC1 character. With ^BC, the invocation
>; selects subset C and >8 inserts FNC1: see our SSCC label guide.
Lines and boxes: ^GB
^GBw,h,t draws a box of width w, height h and line thickness t. A box whose height equals its
thickness is a horizontal line; whose width equals its thickness, a vertical line. ^FR placed before a field reverses it (white on black)
over a filled box.
^XA
^FO20,20^GB760,440,3^FS
^FO20,120^GB760,3,3^FS
^FO20,20^GB760,100,100^FS
^FO40,45^A0N,50,50^FR^FDSHIPPING^FS
^XZ
Quantity, darkness and speed
^PQ10prints 10 copies of the label.~SD20sets the darkness (0 to 30);^PR4sets the print speed (in inches per second, within the printer's limits).^MNYselects gap/notch media sensing,^MNMblack mark,^MNNcontinuous media.~JCruns a media calibration.
Settings sent with a label usually remain until changed or until the printer restarts, depending on the printer configuration. It is good practice to keep media and darkness settings in the printer configuration and send only the label content.
Sending ZPL to a printer
- Raw TCP port 9100: most network label printers accept raw data on port 9100. Any program that opens a socket to
printer-ip:9100and writes the ZPL text prints the label. - Print queue: a Windows queue with a “Generic / Text Only” driver, or a raw CUPS queue, passes the ZPL unchanged.
- File copy: some setups copy a
.zplfile to a shared printer.
To test a printer from macOS or Linux: nc 192.168.1.50 9100 < label.zpl.
From ZPL to automatic printing
Writing ZPL by hand is great for learning and debugging, but in production labels must change with every order, lot or parcel. A print server such as LabelCross Print lets you design the label visually, maps your ERP or WMS data to its variables and generates the ZPL for each record — on Zebra printers and on printers that emulate ZPL. The same design can also print on Honeywell printers in DPL or Fingerprint: see ZPL vs DPL vs Fingerprint.
Reference: Zebra, ZPL II Programming Guide. Command options vary slightly between printer firmware versions; check the guide for your model.
Frequently asked questions
What does ZPL stand for?
ZPL stands for Zebra Programming Language. ZPL II is the current version, used by Zebra industrial and desktop printers and emulated by printers from several other brands.
Which unit does ZPL use for positions?
Dots. Divide the printer resolution by 25.4 to convert millimetres: about 8 dots per mm at 203 dpi, about 12 dots per mm at 300 dpi and about 24 dots per mm at 600 dpi.
How do I print accented characters in ZPL?
Add ^CI28 at the start of the label to tell the printer the field data is UTF-8 encoded, and send the file as UTF-8.
How do I send a ZPL file to a printer?
Open a raw TCP connection to the printer's IP address on port 9100 and send the ZPL text, or copy it to a print queue configured as raw/generic text. A print server such as LabelCross Print does it for you.
Do I have to write ZPL by hand?
No. Label software generates ZPL from a visual design. Writing ZPL by hand is useful to understand, debug or test a printer.