Skip to main content

Zebrafy Logo Zebrafy

CI Documentation Status Zebrafy PyPi Package License

Zebrafy is a Python 3 library for converting PDF and images to and from Zebra Programming Language (ZPL) graphic fields (^GF).

Zebrafy consists of three conversion tools:

  • ZebrafyImage — convert an image into valid ZPL

  • ZebrafyPDF — convert a PDF into valid ZPL

  • ZebrafyZPL — convert valid ZPL graphic fields into images or PDF

If you want more control over the resulting ZPL data, ZebrafyImage and ZebrafyPDF support the following optional parameters:

Parameter

Description

format

ZPL graphic field format type (default "ASCII")

  • "ASCII" — ASCII hexadecimal (most compatible)

  • "B64" — Base64 Binary

  • "Z64" — Z64 compressed binary (best compression)

invert

Invert the black and white in the image/PDF output. (True or False, default False)

dither

Dither the result instead of hard limit on black pixels. (True or False, default True)

threshold

Black pixel threshold for image without dithering (0-255, default 128)

width

Width of the image in the resulting ZPL, 0 to use original image/PDF width (default 0)

height

Height of the image in the resulting ZPL, 0 to use original image/PDF height (default 0)

pos_x

Pixel x position of the graphic field in resulting ZPL (default 0)

pos_y

Pixel y position of the graphic field in resulting ZPL (default 0)

rotation

Rotates the image by the specified degree (0, 90, 180 or 270, default 0)

string_line_break

Number of characters in graphic field content after which a line break is inserted (default None)

complete_zpl

Add ZPL header and footer or only get the ZPL graphic field output (True or False, default True)

Additionally, ZebrafyPDF supports the following optional parameters:

Parameter

Description

dpi

Pixels per PDF canvas unit, defines resolution scaling of the PDF image (<72: compress, >72: stretch, default 72)

split_pages

Split the PDF into separate ZPL labels for each page (True or False, default False)

Getting Started

Installation

pip install zebrafy

Dependencies

Pip handles all dependencies automatically. This library is built on top of:

Example Usage

Image to ZPL Graphic Field with ZebrafyImage

Convert image bytes into a complete ZPL string and save to file:

from zebrafy import ZebrafyImage

with open("source.png", "rb") as image:
    zpl_string = ZebrafyImage(image.read()).to_zpl()

with open("output.zpl", "w") as zpl:
    zpl.write(zpl_string)

Example usage with optional parameters:

from zebrafy import ZebrafyImage

with open("source.png", "rb") as image:
    zpl_string = ZebrafyImage(
        image.read(),
        format="Z64",
        invert=True,
        dither=False,
        threshold=128,
        width=720,
        height=1280,
        pos_x=100,
        pos_y=100,
        rotation=90,
        string_line_break=80,
        complete_zpl=True,
    ).to_zpl()

with open("output.zpl", "w") as zpl:
    zpl.write(zpl_string)

Alternatively, ZebrafyImage also accepts PIL Image as the image parameter instead of image bytes:

from PIL import Image
from zebrafy import ZebrafyImage

pil_image = Image.new(mode="RGB", size=(100, 100))
zpl_string = ZebrafyImage(pil_image).to_zpl()

with open("output.zpl", "w") as zpl:
    zpl.write(zpl_string)

PDF to ZPL Graphic Field with ZebrafyPDF

Convert PDF bytes into a complete ZPL string and save to file:

from zebrafy import ZebrafyPDF

with open("source.pdf", "rb") as pdf:
    zpl_string = ZebrafyPDF(pdf.read()).to_zpl()

with open("output.zpl", "w") as zpl:
    zpl.write(zpl_string)

ZebrafyPDF conversion supports the same optional parameters as ZebrafyImage conversion, with the addition of the split_pages parameter to split the PDF pages:

from zebrafy import ZebrafyPDF

with open("source.pdf", "rb") as pdf:
    zpl_string = ZebrafyPDF(
        pdf.read(),
        format="Z64",
        invert=True,
        dither=False,
        threshold=128,
        dpi=72,
        width=720,
        height=1280,
        pos_x=100,
        pos_y=100,
        rotation=90,
        string_line_break=80,
        complete_zpl=True,
        split_pages=True,
    ).to_zpl()

with open("output.zpl", "w") as zpl:
    zpl.write(zpl_string)

ZPL to PDF or Images with ZebrafyZPL

Convert all graphic fields from a valid ZPL file to PIL Images and save to image files:

from zebrafy import ZebrafyZPL

with open("source.zpl", "r") as zpl:
    pil_images = ZebrafyZPL(zpl.read()).to_images()
    for count, pil_image in enumerate(pil_images):
        pil_image.save(f"output_{count}.png", "PNG")

Convert all graphic fields from a valid ZPL file to PDF bytes and save to PDF file:

from zebrafy import ZebrafyZPL

with open("source.zpl", "r") as zpl:
    pdf_bytes = ZebrafyZPL(zpl.read()).to_pdf()

with open("output.pdf", "wb") as pdf:
    pdf.write(pdf_bytes)

Contributing and Issues

Contributions and bug reports are welcome and can be submitted on the GitHub page.

The project does not yet have a well-defined scope, and I’m open to new feature requests. Features currently in consideration are:

  • HTML to ZPL conversion by implementing standard HTML elements into ZPL commands

  • Extract text from a PDF to render it as a native ZPL command instead of graphic field

License

This source is released under the GNU Lesser General Public License v3.0.

Metadata

Release files for zebrafy 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zebrafy 1.3.0
File Size Uploaded
zebrafy-1.3.0.tar.gz 3.2 MB Details

Built distribution (wheel)

Table of built distributions (wheels) for zebrafy 1.3.0
File Interpreter ABI Platform
zebrafy-1.3.0-py3-none-any.whl Python 3 none any Details

Total release size: 3.3 MB

Release files / zebrafy-1.3.0.tar.gz

Download URL zebrafy-1.3.0.tar.gz
Size 3.2 MB
Tags Source
SHA-256 checksum
How to use checksums
217261d2a9b671caf9a5b35ef3883b1e62518d8e77ce2c3eb2fb78b0b8c75949
BLAKE2b-256 checksum
How to use checksums
1e7a5ed98239ddb6714afa0e094a0914316334f3f2186adb6d296ff5f0d268cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.

Transparency log

Release files / zebrafy-1.3.0-py3-none-any.whl

Download URL zebrafy-1.3.0-py3-none-any.whl
Size 21.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8fbaebe66abe77cedaac203d6cc32ab0f9be003bc1f0cc22c4a0aef808022f32
BLAKE2b-256 checksum
How to use checksums
84909a683b9c4cbb1df423fe92fd30ac72005f9b15db992a5c9ca5e7a5e2af42
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.

Transparency log

Release history Release notifications | RSS feed

2.0.0

2 release files

This release

1.3.0 This release

2 release files

1.2.2

2 release files

1.2.1

2 release files

1.2.0

2 release files

1.1.4

2 release files

1.1.3

1 release file

1.1.2

1 release file

1.1.1

1 release file

1.1.0

2 release files

1.0.1

2 release files

1.0.0

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page