Frequently Asked Questions

What ZPL commands does Labelary support?

See the documentation for a full list of the ZPL commands that are supported.

If you need to use a currently unsupported ZPL command, feel free to let us know. We'll add your request to our backlog and send you an email when we get to it. We also provide commercial support for urgent needs; if you have a time-critical request, just drop us a note and we'll be happy to provide you with an estimate.

What browsers can be used with the online ZPL viewer?

In general, any modern, evergreen browser should work.

Specifically, this means that you should be able to use the latest versions of Firefox, Chrome, Edge and Safari.

Why aren't my labels rendering correctly?

There are a number of reasons that you might be seeing differences between your physical labels and the Labelary output.

First of all, your labels may rely on custom configuration to work correctly. Labelary simulates a new printer with the default factory settings. If your labels rely on custom fonts or images that are not included in each label template, this may result in images that do not match the labels printed by your pre-configured physical printer.

Secondly, your labels may be using a ZPL feature that Labelary does not support or that is supported incorrectly. Check the list of implemented ZPL commands to ensure that all of the commands that are relevant to your use case are supported. If your commands are all supported but you are seeing differences between Labelary's output and your physical labels, drop us a note with an example so that we can fix it and add your test case to the thousands of tests that we already use to verify Labelary's behavior.

Why aren't my labels rendering at all?

If you're using the online viewer, you may be having issues with your firewall. Browsers use Cross-Origin Resource Sharing (CORS) to allow web domains to communicate across domain boundaries. However, some firewalls automatically remove CORS headers from HTTP requests. Browsers need these headers to keep you safe. If these headers are being removed, you'll see errors such as

"XMLHttpRequest cannot load No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin '' is therefore not allowed access"

in your browser console, and you should contact your firewall maintainer or IT department so that they can fix your firewall configuration.

If you're not using the online viewer, or you don't think you are running into the firewall configuration issue described above, then you may have found a bug. We'd appreciate it if you'd send us an email (including the ZPL code that you were using) so that we can investigate!

Why can't I add an image to my label using the online ZPL viewer?

Labelary can read a wide variety of common image formats, but it can't read JPEG images that use a CMYK color model. If you're using a CMYK JPEG image, try converting it to a different format before uploading it. You should have no issues with RGB JPEG images.

If this isn't the problem and you're still having issues adding your image to your label, please send us your ZPL code and your image so that we can investigate!

How can I render Cyrillic / Greek / Chinese / Japanese / Korean / Arabic / other text?

There are two aspects to rendering international text: the encoding and the font.

First of all, make sure that you are using an encoding that supports the international characters that you're trying to render. We suggest using UTF-8 and placing a ^CI28 command at the top of your ZPL template. Be sure to remove any other ^CI commands in your ZPL template.

Second, you will need to use a font which contains glyphs for the international characters that you're trying to render. The ZPL built-in fonts don't support many non-Latin characters, so you may need to use a custom font (uploaded to the printer via the ~DU command, for example). Labelary provides three non-standard international fonts out of the box: font N which provides access to the Google Noto Sans Regular font, font J which provides access to the Google Noto Sans CJK Regular font, and font L which provides access to the Google Noto Sans Arabic Regular font. Feel free to use these fonts in your label designs, but keep in mind that they will not exist on physical printers unless you upload them yourself.

Languages which use mostly Latin characters can usually use the default fonts, as long as the encoding is correct.

Some sample labels using UTF-8 encoding and font 0 (available by default, no custom font necessary):

Some sample labels using UTF-8 encoding and the custom N, J and L fonts:

How can I simulate colored label stock?

You can simulate colored (or partially colored) label stock by using the non-standard ~BR ("background rectangle") and ~BI ("background image") commands.

See here for more information about these commands.

How can I check the status of the Labelary public API?

Use the Labelary status page to check the current status of the public API, as well as 24-hour and 7-day availability statistics.

Note that this is for informational purposes only, since there are no availability guarantees for the public API.

What support / privacy / availability / performance guarantees are provided with the free Labelary web service and the online ZPL viewer?

None. The public web service is a fully-functional instance of the Labelary ZPL rendering engine, provided at no cost for the benefit of label designers around the world. However, there are no SLAs around this service, and all free support is on a best-effort basis.

If you'd like to incorporate Labelary into a business-critical production process, you may want to consider the offline licensing option.

Do you have a paid SaaS offering with extra guarantees around support / privacy / availability / performance?

No, but we are considering such an offering. If you would be interested, please let us know.

Can I use the Labelary engine locally, without relying on the public web service?

We do offer an offline version of the Labelary engine licensed for local use. Please contact us for licensing information.

How can I convert an image to the ZPL image format?

For one-off conversions, we recommend that you just use our online ZPL viewer to add images to your label templates.

If you need to convert batches of images and aren't afraid to get your hands dirty, you can use our (undocumented) image conversion web service. Have a look at the JavaScript in the online viewer page for pointers. Robert Coleman's Labelary Ruby gem also provides a nice Ruby wrapper for the Labelary image conversion web service.

If you'd rather not use our image conversion web service and don't mind forgoing the advanced compression functionality which it provides, have a look at the pyzpl2 project, which provides a simple conversion function here.

Finally, if you'd rather write your own conversion utility, be sure to read the "Alternative Data Compression Scheme for ~DG and ~DB Commands" section of the official ZPL II Programming Guide, Volume 2.