^PW - Print Width
Sets the printable width of the label.
^PW gives a printer how much of its printhead to use — the width of the stock, in dots, so that a
narrower medium prints centered under a wider head. It is the horizontal counterpart of ^LL, and
like ^LL it does not decide the size of the image this API returns: the page dimensions come
from the request. It does shift content here, because a print width narrower than the requested label
centers the printable area within it.
Syntax
^PWaSupport
The command renders, with the caveat below.
The renderer honors this only as a centering offset: a narrower print width centers the content horizontally. It clips only the page an extra-page command injects, and never resizes the page. A width wider than the requested label clamps to the label width, centers nothing, and renders as though no ^PW were present. That matches Labelary. — pinned by test_pw_narrower_than_the_label_still_centres
Labelary renders this command.
Parameters
aLabel widthoptional · dotsPrintable width in dots. On a printer this is the energized span of the printhead, so anything beyond it does not print.
- Default
- the width implied by the requested label size
- Accepted range
- 2 to the width of the label dots
- Invalid value
- discarded, and the current value is kept. A non-numeric argument leaves the previous width in force. A value below 2 raises to 2:
^PW0behaves as^PW2. We measured this on 2026-07-29. - Test coverage
- Bounds pinned: minimum (2), below the minimum (0). No test at the maximum. The invalid-value rule is pinned by 2 tests.
Behavior
Where the request asks for a label W dots wide and ^PWa sets a smaller than W, the renderer
centers the printable area and moves every field right by (W − a) / 2. On a 4-inch label at 8
dot/mm — 812 dots — ^PW400 moves everything right by 206 dots. That offset is the command's whole
effect on the output. It applies to the label, not to the fields that follow, so position in the
format does not matter.
Two consequences matter before a format depends on ^PW:
- The renderer clips only the pages an extra-page command injects. A field that runs past
akeeps its full extent, and the centering offset can push it off the right-hand edge of the page. Labelary clips everything, so a format whose content overflows its print width renders differently here. The deviation below records it. - The renderer clamps a print width larger than the requested label to that label. Nothing
remains to center, so
^PW900on an 812-dot label renders exactly as a format with no^PW. We measured this on Labelary 2026-07-30, where^PW900,^PW812and no^PWat all give the same pixels. Until 2026-07-30 the centering subtraction underflowed instead and the label came back blank.
Below the range, ^PW0 and ^PW1 behave as ^PW2. We measured this on 2026-07-29: both center the
printable area to within a dot of the middle of the page. A non-numeric argument leaves the previous
width alone.
Under ^MU the argument takes the current unit, so ^MUM^PW50 asks for 50 mm.
Tested behavior
Differences from the specification
zpl.tools against the ZPL II guide
Where our renderer behaves differently from the specification.
^PWdoes not change the size of the rendered page; pass the label dimensions in the API request for that. — not pinned by a test- The guide clamps a width beyond the label to the label's maximum size, and the renderer does the same. — pinned by
test_pw_wider_than_the_label_renders_like_no_pw
zpl.tools against Labelary
Where our output differs from Labelary for the same input. These are the differences that break a migration.
- Labelary clips content to the print width; the renderer clips only injected pages. We measured this on 2026-07-29. With
^PW400on a 4-by-2-inch label at 8 dpmm,^FO0,50^GB812,30,30^FSdraws a 400-dot bar on Labelary and a full 812-dot bar here. — not pinned by a test
Example
A 400-dot print width on a 4-inch (812-dot) label. Both fields are placed from ^FO0, and both come out centered 206 dots in — the bar spans exactly the print width:
^XA
^PW400
^FO0,60^GB400,30,30^FS
^FO20,140^A0N,40,40^FDPW400^FS
^XZ
Related commands
^LLLabel LengthSets the label length, for continuous media.^MLMaximum Label LengthTells the printer how far to look for the next label gap.^FOField OriginSets the top-left corner of the next field.^FBField BlockWord-wraps the field's text into a block of a given width.