python-escpos

3.1 verified Fri May 01 auth: no python

Library to manipulate ESC/POS printers. Supports USB, serial, network, and file interfaces. Current version is 3.1 (released 2024-04-07). Requires Python >=3.8.

pip install python-escpos

Common errors

error ValueError: Invalid barcode: '1234567890128' (EAN13) must be 12 or 13 digits. ↓

cause Barcode data length or checksum incorrect. EAN13 requires 13 digits (or 12 with automatic checksum).

fix

Ensure the barcode data is the correct length. For EAN13, provide 12 or 13 numeric digits.

error escpos.exceptions.SetVariableError: Set variable failed for 'some_command' ↓

cause Printer does not support the given command (capability issue).

fix

Check your printer's capabilities and use a different command or update capabilities file.

Warnings

breaking Python 2 support dropped in v3.0. Code relying on Python 2 will break. ↓

fix Upgrade to Python >=3.8.

breaking Import paths changed in v3.0. Printer classes moved to `escpos.printer` submodule. Old imports like `from escpos import Usb` no longer work. ↓

fix Use `from escpos.printer import Usb` (and similarly for Serial, Network, File).

breaking `escpos.escpos.Escpos` base class no longer directly importable. The API for creating printer instances changed. ↓

fix Use the specific printer class from `escpos.printer`.

gotcha USB printer requires `pyusb` and often root/sudo permissions on Linux. Without proper permissions, `Usb` initialization will fail with USBError. ↓

fix Set up udev rules for your printer or run as root.

gotcha Capabilities file must be present for the library to know printer features. If missing, printing may produce garbage or no output. ↓

fix Ensure `python-escpos` is installed correctly; the capabilities are bundled. Alternatively, load a custom capabilities file.

deprecated `escpos.escpos.Escpos.image()` method's parameters changed: `impl` parameter is deprecated in favor of `high_density`. ↓

fix Use `high_density=True` instead of `impl='bitImageColumn'`.

Imports

Usb
wrong
```
from escpos import Usb
```
correct
```
from escpos.printer import Usb
```
Old import path from v2.x; v3.x requires full path from submodule

Serial

wrong

from escpos import Serial

correct

from escpos.printer import Serial

Same as above

Network

wrong

from escpos import Network

correct

from escpos.printer import Network

Same as above

File

wrong

from escpos import File

correct

from escpos.printer import File

Same as above

Quickstart

Basic usage: open USB printer, print text, image, barcode, and cut paper.

from escpos.printer import Usb

# Replace with your printer's USB vendor and product IDs
p = Usb(0x04b8, 0x0202, in_ep=0x82, out_ep=0x01)
p.text("Hello World\n")
p.image("logo.png")
p.barcode("1234567890128", "EAN13", height=100)
p.cut()