What Is ZPL and How Does It Work?

ZPL — Zebra Programming Language — is the command language Zebra thermal printers accept. If you have ever opened a .zpl file and found something like ^XA^FO50,50^A0N,40,40^FDHello^FS^XZ, you have seen a complete label: a series of instructions that tell the printer where to put things and how large to draw them.

Unlike a PDF or an image, a ZPL file describes intent rather than pixels. The same file printed on a 203 dpi printer and a 300 dpi one produces different physical output, which is the single most common source of confusion when a label suddenly comes out wrong.

The shape of a label

Every label is a block bounded by two commands:

^XA          starts the label
...          the field definitions
^XZ          ends the label and prints it

A file can contain many blocks. A batch of fifty shipping labels is fifty ^XA … ^XZ pairs in one text file, and the printer treats each as a separate print job.

Fields

Inside the block, work is organised into fields. A field has an origin, a type and some data:

^FO50,50               field origin: 50 dots right, 50 dots down
^A0N,40,40             font 0, normal orientation, 40 dots tall and wide
^FDHello World^FS      field data, then field separator

^FO is the command you will use most. Its two numbers are dots, not millimetres — and that is where the density question comes in.

Dots, density and physical size

A printer's density is quoted in dots per inch (dpi) or dots per millimetre (dpmm):

| Density | dpmm | 1 inch | | --- | --- | --- | | 203 dpi | 8 dpmm | 203 dots | | 300 dpi | 12 dpmm | 300 dots | | 600 dpi | 24 dpmm | 600 dots |

So ^FO400,0 places a field two inches from the left on a 203 dpi printer, but only 1.33 inches in on a 300 dpi one. If a label that used to fit suddenly overflows the edge, check whether someone swapped the printer model before you start editing coordinates.

Barcodes

Barcodes are fields with a barcode command in front of the data:

^BY2                   module width 2 dots
^BCN,100,Y,N,N         Code 128, 100 dots tall, print the value underneath
^FD123456789^FS

^BY sets the narrow bar width, which controls how wide the finished symbol is. Setting it too low is the usual reason a printed barcode will not scan: at 203 dpi a module width of 2 is a sensible floor.

Other common symbologies follow the same pattern: ^B3 for Code 39, ^BE for EAN-13, ^BQ for QR codes.

Boxes and lines

^GB draws a box, and a box with a thickness equal to its height is a line:

^FO20,20^GB380,180,3^FS     a 380×180 box with a 3-dot border
^FO20,220^GB380,0,3^FS      a horizontal rule

Non-ASCII text

By default the printer interprets bytes in a legacy code page, which is why Turkish characters often print as boxes. Adding ^CI28 near the start of the label switches it to UTF-8:

^XA
^CI28
^FO50,50^A0N,40,40^FDÖzel Ürün^FS
^XZ

The font also has to contain the glyphs. Font 0 covers Latin-1 and most Turkish characters; a font that does not have ğ will still print a box no matter what the code page says.

Checking a label without printing it

The fastest way to learn ZPL is to change a number and see what happens. Paste your code into the ZPL Viewer and it renders exactly what the printer would produce, at the density and label size you choose. When you need to send the result to someone, ZPL to PDF produces a print-ready document at the correct physical size.

The commands worth memorising

| Command | Purpose | | --- | --- | | ^XA / ^XZ | Start and end a label | | ^FO x,y | Field origin in dots | | ^A0N,h,w | Scalable font, height and width in dots | | ^FD … ^FS | Field data, then end of field | | ^GB w,h,t | Box or line | | ^BY w | Barcode module width | | ^BC / ^B3 / ^BE / ^BQ | Code 128 / Code 39 / EAN-13 / QR | | ^CI28 | Switch to UTF-8 | | ^PQ n | Print n copies |

That is enough to read, debug and modify the vast majority of labels you will encounter in a warehouse or an e-commerce operation.