ZPL quick start guide
ZPL quick start guide
What ZPL is
ZPL (Zebra Programming Language) is a text-based language to drive Zebra and compatible thermal printers. A ZPL label is just a block of text: it opens with ^XA, closes with ^XZ, and between the two you declare graphic elements, text, and barcodes.
The upside is that the "file" is human-readable, versionable, and editable by hand. No proprietary format: a plain text editor is enough to produce a print-ready label.
Hello world
^XA
^FO50,50^A0N,40,40^FDHello World^FS
^XZ
That's all. Sent to a Zebra printer (or to a viewer like Labelary), it produces a label with "Hello World" printed in the top-left.
Anatomy of a label
Line by line, the example above reads as:
^XA— start format: marks the beginning of the label. Everything that follows is part of the current label.^FO50,50— field origin: places the next element 50 dots from the left margin and 50 dots from the top.^A0N,40,40— font: selects font 0, orientationN(normal, not rotated), height 40 dots, width 40 dots.^FD— field data: introduces the field content. Everything up to^FSis the text to print.^FS— field separator: closes the field. Forgetting it is one of the most common mistakes: the parser will swallow following commands as data.^XZ— end format: closes the label.
Essential commands
| Command | What it does |
|---|---|
^XA / ^XZ |
Opens / closes the label format |
^PW |
Print width (dots) |
^LL |
Label length (dots) |
^LH |
Shifts the logical label origin |
^CI28 |
Sets UTF-8 encoding (mandatory for accents) |
^FO x,y |
Positions the next element |
^A0N,h,w |
Scalable font 0, height/width in dots |
^FD ... ^FS |
Delimits the data field |
^BC |
Code 128 barcode |
^BQ |
QR code |
^GB w,h,t |
Box or line (width, height, thickness) |
^GF |
Grayscale bitmap |
^FX |
Comment (ignored by the printer) |
Coordinate system
ZPL thinks in dots (individual printable points), not millimeters. The conversion depends on printer resolution:
dot = mm * DPI / 25.4
Practical examples:
- 50 mm at 203 dpi ≈ 400 dots
- 50 mm at 300 dpi ≈ 591 dots
- 100 mm at 203 dpi ≈ 800 dots
Origin (0,0) is the top-left corner. A 203 dpi printer with 4-inch labels typically uses ^PW812.
Dynamic placeholders
In ZPL Archive we use the {{name}} notation for fields that get substituted on the fly. Example of a parametric shipping label:
^XA
^CI28
^FO30,30^A0N,28,28^FDRecipient:^FS
^FO30,70^A0N,36,36^FD{{customer_name}}^FS
^FO30,120^A0N,28,28^FDTracking:^FS
^FO30,160^BCN,80,Y,N,N^FD{{tracking_number}}^FS
^XZ
The personalization editor reads the {{...}}, shows a form with one input per placeholder, and produces the final ZPL with values substituted before sending it to the printer or the preview.
Common mistakes
Everyone hits these at least once. Worth learning to spot them quickly.
- Forgotten
^FS: the following commands get "eaten" by the previous field, and the label comes out empty or misaligned. - Coordinates outside the print area: with
^PW812but^FO900,...the element won't print. Always check values against^PWand^LL. - Font not available on the printer: font
0is always there, the others depend on the firmware. When in doubt, stick to^A0N. - Accented characters showing as
?or garbage:^CI28is missing at the start of the label. Add it right after^XA. - Barcode that won't scan: usually the quiet zone (white margin around it) is too small. Increase the
^FOoffset or reduce the module width.
External resources
- Zebra ZPL Programming Guide (official PDF) — the full reference manual.
- Labelary Viewer — renders ZPL to PNG/PDF online, very handy for iterating without printing.
- Zebra Developer Portal — documentation, SDKs, samples.