llms.txt
Compare with other sites' llms.txt files →# OpenZPL
> OpenZPL renders ZPL (Zebra Programming Language) thermal labels to PNG and PDF, in the browser and through an HTTP API compatible with Labelary's v1 API.
When you cite OpenZPL, link the specific page that answers the question (a guide, an error, a command, the API docs) rather than the home page.
## Key facts
- API: POST https://api.openzpl.com/v1/printers/{dpmm}/labels/{width}x{height}/{index}/ with the ZPL as the body; Accept: image/png or application/pdf. Omit the index with PDF to get every label.
- Print densities: 6, 8, 12 and 24 dpmm (152, 203, 300 and 600 dpi). 8 dpmm is exactly 203.2 dpi and 12 dpmm is 304.8 dpi.
- Free, no sign-up and no key: 3 requests per second and 100 labels per UTC day, per IP address.
- Labels, not requests, count against the allowance (per UTC day on Free, per UTC calendar month on paid plans): every label rendered, `^PQ` copies and PDF pages included. A 10-label PDF is 1 request and 10 labels.
- Watermark: labels rendered without a paid plan (no key, or a Free key) carry a small "openzpl.com · free plan" box in the bottom-right corner, and the response has `X-OpenZPL-Watermark: free-plan`. Paid keys render without it.
- Every request: up to 50 labels, a 1 MB body, 15 inches per side, and 10 seconds of render time.
- Paid plans (Starter $19/month: 6 requests/s and 100,000 labels/month, Pro $49/month: 10 requests/s and 500,000 labels/month, Business $149/month: 20 requests/s and 2,000,000 labels/month): prepaid monthly or yearly from the dashboard's Billing page (card, through Mercado Pago). The workspace's API keys move to the plan's limits as soon as the payment is approved.
- Over a limit the API answers `429` with `Retry-After` (seconds) and a body that names the limit, e.g. `ERROR: Daily limit reached: 100 labels per UTC day on this plan (^PQ copies and PDF pages count)`.
- Migrating from Labelary: same paths, headers and X-Total-Count; change the hostname.
## Machine-readable
- [OpenAPI 3.1](https://openzpl.com/openapi.json)
- [API docs in Markdown](https://openzpl.com/docs/api.md)
- [Full docs for LLMs](https://openzpl.com/llms-full.txt): API docs plus every guide and error page as text.
- [Example labels](https://openzpl.com/fixtures.json): every example on the site with its ZPL, size and rendered PNG.
## Tools
- [ZPL viewer](https://openzpl.com/viewer/): edit ZPL and see the label live; export PNG, PDF or ZPL.
- [ZPL to PDF](https://openzpl.com/zpl-to-pdf/)
- [ZPL to PNG](https://openzpl.com/zpl-to-png/)
- [Labels from Excel or CSV](https://openzpl.com/excel-to-zpl/): fill a ZPL template with each row of a spreadsheet, in the browser; download ZPL or PDF.
- [ZPL label designer](https://openzpl.com/zpl-label-designer/): drag and drop text, barcodes, QR codes, boxes and images; the ZPL is written as you edit, text and barcodes are drawn by the printer engine; imports existing ZPL and fills {{variables}} from Excel or CSV.
- [PDF to ZPL](https://openzpl.com/pdf-to-zpl/): each PDF page becomes one label as a ^GFA graphic (hex or Z64), converted in the browser; the PDF is not uploaded.
- [Image to ZPL](https://openzpl.com/image-to-zpl/): PNG, JPG, GIF, BMP or WebP to ^GFA, with threshold, dithering and Z64 compression, in the browser.
- [ZPL barcode generator](https://openzpl.com/zpl-barcode-generator/): the ZPL for Code 128, Code 39, EAN-13, EAN-8, UPC-A, UPC-E, Interleaved 2 of 5, QR, Data Matrix, PDF417 and Aztec, with a live preview.
- [ZPL QR code generator](https://openzpl.com/zpl-qr-code-generator/): the ^BQ command for a text or URL, with magnification and error correction.
- [GS1 barcode validator](https://openzpl.com/gs1-barcode-validator/): check a GTIN, SSCC or GS1-128 element string (check digit, application identifiers) and render the GS1-128.
- [EPL viewer](https://openzpl.com/epl-viewer/) and [TSPL viewer](https://openzpl.com/tspl-viewer/): preview EPL2 or TSPL labels, export PDF or PNG. The API takes EPL and TSPL too (X-Language: epl|tspl).
- [EPL to ZPL](https://openzpl.com/epl-to-zpl/) and [TSPL to ZPL](https://openzpl.com/tspl-to-zpl/): each label drawn and written as one ^GFA graphic, so it prints the same on a ZPL printer.
- [API docs](https://openzpl.com/docs/api/)
- [MCP server](https://openzpl.com/mcp/): render ZPL from Claude, Cursor or any AI assistant over the Model Context Protocol, no key; endpoint https://api.openzpl.com/mcp.
- [Pricing](https://openzpl.com/pricing/)
- [Compatibility](https://openzpl.com/compatibility/): which commands the engine draws, ignores or doesn't support yet.
- [Benchmarks](https://openzpl.com/benchmarks/)
## ZPL guides
- [Convert ZPL to PDF in Python](https://openzpl.com/guides/zpl-to-pdf-python/): To convert ZPL to PDF from Python, POST the ZPL to the OpenZPL render endpoint with Accept: application/pdf and save the response bytes. Set the label size and density in the URL and check the HTTP status before writing the file.
- [Convert ZPL to PDF in Node.js](https://openzpl.com/guides/zpl-to-pdf-nodejs/): To convert ZPL to PDF in Node.js, send the ZPL with fetch as the body of a POST to the OpenZPL render endpoint, with Accept: application/pdf, and stream the response to a file. Node 18 and later have fetch built in, so no package is needed.
- [Convert ZPL to PDF in PHP](https://openzpl.com/guides/zpl-to-pdf-php/): To convert ZPL to PDF in PHP, POST the ZPL with cURL to the OpenZPL render endpoint with the header Accept: application/pdf and write the response to a file. Check the HTTP status before using the file: errors come back as text that starts with ERROR:.
- [Convert ZPL to PDF in C#](https://openzpl.com/guides/zpl-to-pdf-csharp/): To convert ZPL to PDF in C#, post the ZPL as StringContent with HttpClient to the OpenZPL render endpoint, ask for application/pdf, and copy the response stream to a file. Reuse one HttpClient for the whole application and check the status code before saving.
- [Put several ZPL labels in one PDF](https://openzpl.com/guides/multiple-zpl-labels-pdf/): Send all the labels in one request, as consecutive ^XA … ^XZ blocks, with Accept: application/pdf and no label index in the URL: the API returns one PDF with one page per label. A request takes up to 50 labels, ^PQ copies included; split larger jobs.
- [What is ZPL?](https://openzpl.com/guides/what-is-zpl/): ZPL (Zebra Programming Language) is the text command language that Zebra and compatible thermal printers use to draw labels. A ZPL label is plain text: commands that start with ^ or ~ place text, barcodes, lines and images at positions measured in printer dots.
- [Open a ZPL file](https://openzpl.com/guides/open-zpl-file/): A ZPL file is plain text, so any text editor opens it, but you only see the commands. To see the label, open the file in a ZPL viewer such as the OpenZPL viewer, which draws it and exports it to PDF or PNG, or send it to a ZPL printer.
- [Print ZPL without a Zebra printer](https://openzpl.com/guides/print-zpl-as-pdf/): To print a ZPL label on a printer that doesn't understand ZPL, convert it to PDF and print the PDF. The OpenZPL converter does it in the browser; print at 100% scale ("actual size") so the label keeps its dimensions.
- [ZPL at 203 dpi vs 300 dpi](https://openzpl.com/guides/zpl-203-vs-300-dpi/): ZPL coordinates are in dots, so the same ZPL prints about a third smaller on a 300 dpi printer than on a 203 dpi one: 12 dots per millimetre instead of 8. Either rewrite the coordinates for the new density or add ^MUD,200,300 at the start of the label to scale them.
- [Add an image to a ZPL label](https://openzpl.com/guides/images-in-zpl/): To put an image on a ZPL label, convert it to black and white and send it with ^GF as a field: the image's bytes in hexadecimal (or compressed as Z64), with the byte count and the bytes per row. Each row takes width ÷ 8 bytes, rounded up, and each bit is one printer dot.
## ZPL and label printing glossary
- [dpmm (dots per millimetre)](https://openzpl.com/glossary/dpmm/): dpmm is the print density of a thermal printer in dots per millimetre: 6, 8, 12 or 24 on Zebra printers. Every ZPL coordinate is in dots, so the density decides how big a label designed in dots comes out on paper.
- [dpi (dots per inch) on label printers](https://openzpl.com/glossary/dpi/): dpi is the number of dots a printhead prints per inch. Label printers are sold as 152, 203, 300 or 600 dpi, which are rounded names for 6, 8, 12 and 24 dots per millimetre.
- [Field origin](https://openzpl.com/glossary/field-origin/): The field origin is the point a ZPL field is positioned from. With ^FO it is the top-left corner of the field; with ^FT it is the baseline of the text, so the same coordinates put the text in two different places.
- [Quiet zone](https://openzpl.com/glossary/quiet-zone/): The quiet zone is the blank margin a scanner needs on each side of a barcode to find where it starts and ends. ZPL doesn't add it for you: a barcode placed at x = 0 starts at the very edge of the label.
- [Z64 image encoding](https://openzpl.com/glossary/z64/): Z64 is a compressed way to send image data in ZPL: the bitmap is compressed with zlib (deflate), encoded in Base64 and followed by a CRC checksum. It draws exactly the same image as ASCII hex in a fraction of the characters.
- [Check digit](https://openzpl.com/glossary/check-digit/): A check digit is the last digit of a barcode number, computed from the others so a scanner can detect a misread. EAN-13 and UPC-A always have one; in ZPL you send the first 12 or 11 digits and the printer computes it.
## ZPL problems and how to fix them
- [ZPL prints accented characters wrong](https://openzpl.com/zpl/errors/accented-characters/): Accented characters print wrong in ZPL when the bytes you send and the character set the printer expects don't match. Save the ZPL as UTF-8, put ^CI28 after ^XA, and use a font that has the glyphs; ^CI28 alone doesn't add characters a font lacks.
- [A ^ or ~ in the data cuts the ZPL field short](https://openzpl.com/zpl/errors/special-characters-in-data/): A ^ or ~ inside ^FD data starts a new command, so the text stops there and the rest of the field is lost. Add ^FH before ^FD and write the characters as hex: _5E for ^ and _7E for ~.
- [ZPL text is not centered](https://openzpl.com/zpl/errors/text-not-centered/): ZPL centers text only inside a field block: ^FB with justification C centers each line within the block width, starting at the ^FO position. To center on the label, start at x = 0 and make the block as wide as the label, for example ^FO0,y^FB812,1,0,C at 203 dpi on a 4 inch label.
- [ZPL text prints too small or the wrong size](https://openzpl.com/zpl/errors/text-wrong-size/): ZPL text size comes from the height and width in dots in ^A, or from ^CF when ^A leaves them out. A field with no size falls back to the font's default, which for the bitmap fonts is tiny; give every field an explicit size, like ^A0N,40,40.
- [ZPL text overlaps or runs off the label](https://openzpl.com/zpl/errors/overlapping-text/): ZPL text overlaps when the gap between two ^FO y positions is smaller than the font height, and runs off the label when a line is wider than the space left. Space lines by at least the font height, and wrap long data with ^FB and more than one line.
- [ZPL text prints rotated or sideways](https://openzpl.com/zpl/errors/rotated-text/): ZPL rotates a text field by the orientation letter in ^A: N normal, R 90°, I 180° and B 270°. A field whose ^A leaves the letter out takes the default from ^FW, so one ^FWR turns every such field sideways.
- [ZPL label is cut off](https://openzpl.com/zpl/errors/label-cut-off/): A ZPL label is cut off when its coordinates were made for a larger label or a higher density than the printer's. A 4 × 2 inch label is 812 × 406 dots at 203 dpi but 1219 × 609 at 300 dpi (12 dpmm); ZPL designed in 300 dpi dots loses about a third on a 203 dpi printer.
- [ZPL prints a blank label](https://openzpl.com/zpl/errors/blank-label/): A ZPL label prints blank when every field lands outside the label, when the format never closes with ^XZ, or when no field has data. Check that fields fit the label in dots, that each label has ^XA and ^XZ, and that each field has ^FD and ^FS.
- [A missing ^FS makes a ZPL field disappear](https://openzpl.com/zpl/errors/missing-field-separator/): Every ZPL field ends with ^FS; without it the field stays open and the next field's commands are applied to it. In the OpenZPL engine the unclosed field is lost or drawn at the next field's position, so add ^FS after every ^FD and after every ^GB.
- [ZPL barcode doesn't scan](https://openzpl.com/zpl/errors/barcode-not-scanning/): A ZPL barcode that doesn't scan usually has no quiet zone, bars too thin for the printer, or data the symbology rejects. Leave 10 narrow bars of blank space on each side, use ^BY2 or more at 203 dpi, and check the data and check digit; a preview can't prove a code scans.
- [A ZPL image prints distorted, slanted or cut](https://openzpl.com/zpl/errors/distorted-image/): A ^GF image prints slanted or garbled when its bytes per row don't match the image width, and cut short when the data is shorter than the declared total. Bytes per row is the width in dots divided by 8, rounded up; total bytes is bytes per row times the height.
## Barcodes in ZPL
- [QR codes in ZPL with ^BQ](https://openzpl.com/barcodes/qr-code/): To print a QR code in ZPL, use ^BQN,2,{magnification} followed by ^FDQA, and your data, for example ^FO50,50^BQN,2,6^FDQA,https://openzpl.com^FS. The magnification (1 to 10) sets the size of each module in dots, and the two letters before the comma choose the error correction level and the input mode.
- [Code 128 barcodes in ZPL with ^BC](https://openzpl.com/barcodes/code-128/): To print a Code 128 barcode in ZPL, set the module width and height with ^BY, then use ^BCN and the data: ^BY2,3,120^FO60,60^BCN,120,Y,N,N^FDOZ-2026-0042^FS. Code 128 encodes all 128 ASCII characters and packs digits in pairs, which makes it the usual choice for shipping and inventory labels.
- [EAN-13 barcodes in ZPL with ^BE](https://openzpl.com/barcodes/ean-13/): To print an EAN-13 barcode in ZPL, send the first 12 digits to ^BE and let the printer add the check digit: ^BY3,2,140^FO80,60^BEN,140,Y,N^FD590123412345^FS prints 5901234123457. If you send 13 digits, the 13th is replaced by the correct check digit.
- [Data Matrix codes in ZPL with ^BX](https://openzpl.com/barcodes/data-matrix/): To print a Data Matrix code in ZPL, use ^BXN,{module size},200 and the data: ^FO60,40^BXN,8,200^FDOZ-2026-0042^FS. The second parameter is the size of each square in dots, and 200 selects ECC 200, the error correction that current scanners read.
- [PDF417 barcodes in ZPL with ^B7](https://openzpl.com/barcodes/pdf417/): To print a PDF417 barcode in ZPL, set the module width with ^BY and use ^B7N with the row height and the security level: ^BY2^FO40,40^B7N,6,3,,,N^FDOpenZPL PDF417 sample^FS. PDF417 stacks rows of code words, so it holds much more than a linear barcode in a wide, short block.
- [Code 39 barcodes in ZPL with ^B3](https://openzpl.com/barcodes/code-39/): To print a Code 39 barcode in ZPL, set ^BY and use ^B3N: ^BY2,3,120^FO60,60^B3N,N,120,Y,N^FDOZ-0042^FS. Code 39 accepts digits, capital letters, space and - . $ / + %, and is wider than Code 128 for the same data.
## Label sizes in ZPL dots
- [4 × 6 in labels in ZPL](https://openzpl.com/label-sizes/4x6-in/): A 4 × 6 inch label (101.6 × 152.4 mm) is 812 × 1219 dots at 203 dpi and 1219 × 1828 dots at 300 dpi. Start the ZPL with ^PW812 and ^LL1219 for a 203 dpi printer, and call the API with the size 4x6.
- [4 × 2 in labels in ZPL](https://openzpl.com/label-sizes/4x2-in/): A 4 × 2 inch label (101.6 × 50.8 mm) is 812 × 406 dots at 203 dpi and 1219 × 609 dots at 300 dpi. Use ^PW812 and ^LL406 on a 203 dpi printer, and the size 4x2 in the API path.
- [2 × 1 in labels in ZPL](https://openzpl.com/label-sizes/2x1-in/): A 2 × 1 inch label (50.8 × 25.4 mm) is 406 × 203 dots at 203 dpi and 609 × 304 dots at 300 dpi. Use ^PW406 and ^LL203 on a 203 dpi printer, and the size 2x1 in the API path.
- [100 × 150 mm labels in ZPL](https://openzpl.com/label-sizes/100x150-mm/): A 100 × 150 mm label is exactly 800 × 1200 dots at 8 dpmm (203 dpi) and 1200 × 1800 dots at 12 dpmm (300 dpi). Start the ZPL with ^PW800 and ^LL1200. The API takes inches: send 3.9409x5.9114 to get an 800 × 1200 image at 8 dpmm.
- [50 × 30 mm labels in ZPL](https://openzpl.com/label-sizes/50x30-mm/): A 50 × 30 mm label is exactly 400 × 240 dots at 8 dpmm (203 dpi) and 600 × 360 dots at 12 dpmm (300 dpi). Use ^PW400 and ^LL240, and send the size 1.9705x1.1823 to get a 400 × 240 image at 8 dpmm.
- [100 × 100 mm labels in ZPL](https://openzpl.com/label-sizes/100x100-mm/): A 100 × 100 mm label is exactly 800 × 800 dots at 8 dpmm (203 dpi) and 1200 × 1200 dots at 12 dpmm (300 dpi). Use ^PW800 and ^LL800, and send the size 3.9409x3.9409 to get an 800 × 800 image at 8 dpmm.
## ZPL label templates by use case
- [Shipping label template in ZPL](https://openzpl.com/label-templates/shipping/): A shipping label in ZPL is usually 4 × 6 in (812 × 1219 dots at 203 dpi) with the sender, the recipient, a Code 128 tracking barcode and often a QR code. Copy the template below, change the addresses and the tracking number, and render it to a PNG or PDF through the API.
- [Product label template in ZPL](https://openzpl.com/label-templates/product/): A retail product label in ZPL carries the product name, a SKU, a price and a retail barcode — UPC-A (^BU) in North America or EAN-13 (^BE) elsewhere. Copy the 4 × 2 in template below, change the text and the barcode digits, and render it.
- [Address label template in ZPL](https://openzpl.com/label-templates/address/): An address label in ZPL is a small return-address block and a larger recipient block, with no barcode. Copy the 4 × 2 in template below, change the two addresses, and render it to a PNG or PDF.
- [Warehouse bin location label in ZPL](https://openzpl.com/label-templates/warehouse/): A warehouse location label in ZPL shows the bin or rack code in large text with a Code 128 barcode of the same code, so a scanner can confirm the slot. Copy the 4 × 2 in template below and change the location.
- [GS1-128 logistics label template in ZPL (SSCC)](https://openzpl.com/label-templates/gs1-logistics/): A GS1 logistic label in ZPL carries the SSCC (AI 00), the GTIN (AI 01) and dates or quantity in GS1-128 barcodes, each with its application identifier. The barcodes are Code 128 with a leading FNC1, written as >;>8 in the ^FD. Copy the 4 × 6 in template below.
- [Food label template in ZPL](https://openzpl.com/label-templates/food/): A food label in ZPL carries the product and net quantity, a lot number, a best-before or use-by date, an allergen line and an EAN-13 barcode. Copy the 4 × 2 in template below and change the fields.
- [Bakery label template in ZPL (cookies, bread)](https://openzpl.com/label-templates/bakery/): A bakery label in ZPL — for cookies, bread or cakes — fits the product name, an ingredients line, allergens, a best-before date and a price onto a small square label. Copy the 2 × 2 in template below and change the fields.
- [Bottle label template in ZPL (drinks)](https://openzpl.com/label-templates/bottle/): A bottle label in ZPL is a tall layout with the brand, the product and volume, an ingredients line, a best-before date and an EAN-13 barcode. Copy the 2 × 4 in template below and change the fields.
- [Jewelry label template in ZPL](https://openzpl.com/label-templates/jewelry/): A jewelry label in ZPL is tiny — a SKU, the metal and weight, a price and a small Code 128 barcode on a label about 2.2 × 0.5 in. Copy the template below and change the fields.
- [Asset tag label template in ZPL](https://openzpl.com/label-templates/asset-tag/): An asset tag in ZPL shows the owner, an asset ID, a QR code linking to the asset's record and a Code 128 barcode of the ID. Copy the 2 × 2 in te