The ZPL commands you will actually run into
Zebra's manual lists over two hundred commands. A shipping label uses fewer than twenty. This is that list, with what each one does and the mistake each one tends to cause.
The smallest useful label
Every ZPL label has the same frame: open, describe fields, close. This is the smallest one that does anything:
^XA
^CI28
^FO50,50^A0N,40,40^FDPedido 1234^FS
^XZFour lines, each with one job: open, declare the file as UTF-8, draw some text at a position, close. Everything else is a variation on that.
The detail that trips up newcomers: every measurement in ZPL is in dots, not millimetres. How many dots fit in a millimetre depends on the printer's density, which is why there is a whole guide about density.
Structure
| Command | What it does |
|---|---|
| ^XA | Opens a label. Every label starts here. |
| ^XZ | Closes the label. Without it, the label is lost in silence. |
| ^CI28 | Declares the file's text as UTF-8. Without it, accented characters come out garbled. |
| ^FS | Closes a field. Miss one and the next field is swallowed as if it were text. |
| ^FX | A comment. Ignored on conversion, useful to whoever reads the file later. |
| ^LH | Shifts the origin of the whole label. Handy for fixing a margin without touching every field. |
Position and text
| Command | What it does |
|---|---|
| ^FO x,y | Positions the next field, measured from the top left corner, in dots. |
| ^FT x,y | Positions by the text baseline instead of the top. Useful for lining up text of different sizes. |
| ^A0 o,h,w | Scalable font. First value is the orientation (N, R, I, B), then height and width in dots. |
| ^FD | The field's content: what actually prints. |
| ^FB w,n,s,j,i | A text block with automatic wrapping: width, line count, line spacing, alignment. |
The orientation inside ^A0 is what actually rotates text. ^A0N is normal and ^A0R turns it 90 degrees. We tested both.
Drawing and barcodes
| Command | What it does |
|---|---|
| ^GB w,h,t | Draws a rectangle. With a height or width of 1 it becomes a divider line. |
| ^BY w,r,h | Sets bar width, ratio and height for the barcodes that follow. The default matches ^BY2. |
| ^BC | Code 128, the linear barcode of shipping labels. |
| ^BQ | QR Code. |
| ^BX | Data Matrix. |
| ^GFA | An embedded image, dot by dot. This is what carries a logo inside the file. |
^BY applies from where it appears to the end of the label, not just to the next barcode. In a file with two barcodes of different sizes, ^BY has to be repeated before the second one.
The ones you can ignore when converting
Several commands that show up constantly do nothing in a PDF, because they describe the machine rather than the drawing: ^PQ (copies), ^PW and ^LL (size), ^MD (darkness), ^PR (speed), ^PO (paper orientation).
None of them is a mistake in the file, and none changes what conversion produces. The guide on ignored commands explains each one, with what we measured.
How to read a file you did not write
The reading order that works: find the ^XA marks to learn how many labels there are, then read one block top to bottom. Each ^FS marks the end of an element, so counting ^FS gives you the number of things drawn.
Inside a block, ^FO and ^FD pairs are the skeleton: one says where, the other says what. An ^FD with no ^FO before it does not inherit the previous field's position, intuitive as that sounds: it goes to the top left corner. We tested it, and it is the same corner a field ends up in when its ^FO is mistyped.