Printers

Last Reviewed:: 2023-08-23

As of now there are 8 different types of printer implementations.

USB

The USB-class uses pyusb and libusb to communicate with USB-based printers.

Note

This driver is not suited for USB-to-Serial-adapters and similar devices, but only for those implementing native USB.

class escpos.printer.Usb(idVendor=None, idProduct=None, usb_args={}, timeout=0, in_ep=130, out_ep=1, *args, **kwargs)[source]

USB printer.

This class describes a printer that natively speaks USB.

inheritance:

static is_usable()[source]

Indicate whether this printer class is usable.

Will return True if dependencies are available. Will return False if not.

Return type:: bool

__init__(idVendor=None, idProduct=None, usb_args={}, timeout=0, in_ep=130, out_ep=1, *args, **kwargs)[source]

Initialize USB printer.

Parameters:

idVendor (Optional[int]) – Vendor ID
idProduct (Optional[int]) – Product ID
usb_args (Dict[str, Union[str, int]]) – Optional USB arguments (e.g. custom_match)
timeout (Union[int, float]) – Is the time limit of the USB operation. Default without timeout.
in_ep (int) – Input end point
out_ep (int) – Output end point

open(raise_not_found=True)[source]

Search device on USB tree and set it as escpos device.

By default raise an exception if device is not found.

Parameters:: raise_not_found (bool) – Default True. False to log error but do not raise exception.
Raises:: DeviceNotFoundError
Raises:: USBNotFoundError
Return type:: None

close()[source]

Release USB interface.

Return type:: None

Serial

This driver uses pyserial in order to communicate with serial devices. If you are using an USB-based adapter to connect to the serial port, then you should also use this driver. The configuration is often based on DIP-switches that you can set on your printer. For the hardware-configuration please refer to your printer’s manual.

class escpos.printer.Serial(devfile='', baudrate=9600, bytesize=8, timeout=1, parity=None, stopbits=None, xonxoff=False, dsrdtr=True, *args, **kwargs)[source]

Serial printer.

This class describes a printer that is connected by serial interface.

inheritance:

static is_usable()[source]

Indicate whether this printer class is usable.

Will return True if dependencies are available. Will return False if not.

Return type:: bool

__init__(devfile='', baudrate=9600, bytesize=8, timeout=1, parity=None, stopbits=None, xonxoff=False, dsrdtr=True, *args, **kwargs)[source]

Initialize serial printer.

Parameters:

devfile (str) – Device file under dev file system
baudrate (int) – Baud rate for serial transmission
bytesize (int) – Serial buffer size
timeout (Union[int, float]) – Read/Write timeout
parity (Optional[str]) – Parity checking
stopbits (Optional[int]) – Number of stop bits
xonxoff (bool) – Software flow control
dsrdtr (bool) – Hardware flow control (False to enable RTS/CTS)

open(raise_not_found=True)[source]

Set up serial port and set is as escpos device.

By default raise an exception if device is not found.

Parameters:: raise_not_found (bool) – Default True. False to log error but do not raise exception.
Raises:: DeviceNotFoundError
Return type:: None

close()[source]

Close Serial interface.

Return type:: None

Network

This driver is based on the socket class.

class escpos.printer.Network(host='', port=9100, timeout=60, *args, **kwargs)[source]

Network printer.

This class is used to attach to a networked printer. You can also use this in order to attach to a printer that is forwarded with socat.

If you have a local printer on parallel port /dev/usb/lp0 then you could start socat with:

socat -u TCP4-LISTEN:4242,reuseaddr,fork OPEN:/dev/usb/lp0

Then you should be able to attach to port 4242 with this class. Otherwise the normal use case would be to have a printer with Ethernet interface. This type of printer should work the same with this class. For the address of the printer check its manuals.

inheritance:

static is_usable()[source]

Indicate whether this printer class is usable.

Will return True if dependencies are available. Will return False if not.

Return type:: bool

__init__(host='', port=9100, timeout=60, *args, **kwargs)[source]

Initialize network printer.

Parameters:

host (str) – Printer’s host name or IP address
port (int) – Port to write to
timeout (Union[int, float]) – timeout in seconds for the socket-library

open(raise_not_found=True)[source]

Open TCP socket with socket-library and set it as escpos device.

By default raise an exception if device is not found.

Parameters:: raise_not_found (bool) – Default True. False to log error but do not raise exception.
Raises:: DeviceNotFoundError
Return type:: None

close()[source]

Close TCP connection.

Return type:: None

Troubleshooting

Problems with a network-attached printer can have numerous causes. Make sure that your device has a proper IP address. Often you can check the IP address by triggering the self-test of the device. As a next step try to send text manually to the device. You could use for example:

echo "OK\n" | nc IPADDRESS 9100
# the port number is often 9100

As a last resort try to reset the interface of the printer. This should be described in its manual.

File

This printer “prints” just into a file-handle. Especially on *nix-systems this comes very handy.

class escpos.printer.File(devfile='', auto_flush=True, *args, **kwargs)[source]

Generic file printer.

This class is used for parallel port printer or other printers that are directly attached to the file system. Note that you should stay away from using USB-to-Parallel-Adapter since they are unreliable and produce arbitrary errors.

inheritance:

static is_usable()[source]

Indicate whether this printer class is usable.

Will return True if dependencies are available. Will return False if not.

Return type:: bool

__init__(devfile='', auto_flush=True, *args, **kwargs)[source]

Initialize file printer with device file.

Parameters:

devfile (str) – Device file under dev file system
auto_flush (bool) – automatically call flush after every call of _raw()

open(raise_not_found=True)[source]

Open system file.

By default raise an exception if device is not found.

Parameters:: raise_not_found (bool) – Default True. False to log error but do not raise exception.
Raises:: DeviceNotFoundError
Return type:: None

flush()[source]

Flush printing content.

Return type:: None

close()[source]

Close system file.

Return type:: None

Dummy

The Dummy-printer is mainly for testing- and debugging-purposes. It stores all of the “output” as raw ESC/POS in a string and returns that.

class escpos.printer.Dummy(*args, **kwargs)[source]

Dummy printer.

This class is used for saving commands to a variable, for use in situations where there is no need to send commands to an actual printer. This includes generating print jobs for later use, or testing output.

inheritance:

static is_usable()[source]

Indicate whether this printer class is usable.

Will return True if dependencies are available. Will return False if not.

Return type:: bool

property output: bytes: Get the data that was sent to this printer.

clear()[source]

Clear the buffer of the printer.

This method can be called if you send the contents to a physical printer and want to use the Dummy printer for new output.

Return type:: None

close()[source]

Close not implemented for Dummy printer.

Return type:: None

CUPS

This driver uses pycups in order to communicate with a CUPS server. Supports both local and remote CUPS printers and servers. The printer must be properly configured in CUPS administration. The connector generates a print job that is added to the CUPS queue.

class escpos.printer.CupsPrinter(printer_name='', *args, **kwargs)[source]

Simple CUPS printer connector.

Note

Requires pycups which in turn needs the cups development library package:

Ubuntu/Debian: libcups2-dev
OpenSuse/Fedora: cups-devel

inheritance:

static is_usable()[source]

Indicate whether this printer class is usable.

Will return True if dependencies are available. Will return False if not.

Return type:: bool

property printers: dict: Available CUPS printers.

open(job_name='python-escpos', raise_not_found=True)[source]

Set up a new print job and target the printer.

A call to this method is required to send new jobs to the CUPS connection after close.

Defaults to default CUPS printer. Creates a new temporary file buffer.

By default raise an exception if device is not found.

Parameters:: raise_not_found (bool) – Default True. False to log error but do not raise exception.
Raises:: DeviceNotFoundError
Return type:: None

send()[source]

Send the print job to the printer.

Return type:: None

close()[source]

Close CUPS connection.

Send pending job to the printer if needed.

Return type:: None

LP

This driver uses the UNIX command lp in order to communicate with a CUPS server. Supports local and remote CUPS printers. The printer must be properly configured in CUPS administration. The connector spawns a new sub-process where the command lp is executed.

No dependencies required, but somehow the print queue will affect some print job such as barcode.

class escpos.printer.LP(printer_name='', *args, **kwargs)[source]

Simple UNIX lp command raw printing.

Thanks to Oyami-Srk comment.

inheritance:

static is_usable()[source]

Indicate whether this printer class is usable.

Will return True if dependencies are available. Will return False if not.

Return type:: bool

__init__(printer_name='', *args, **kwargs)[source]

LP class constructor.

Parameters:

printer_name (str) – CUPS printer name (Optional)
auto_flush (bool (Defaults False)) – Automatic flush after every _raw() (Optional)

property printers: dict: Available CUPS printers.

open(job_name='python-escpos', raise_not_found=True, _close_opened=True)[source]

Invoke _lp_ in a new subprocess and wait for commands.

By default raise an exception if device is not found.

Parameters:: raise_not_found (bool) – Default True. False to log error but do not raise exception.
Raises:: DeviceNotFoundError
Return type:: None

close()[source]

Stop the subprocess.

Return type:: None

flush()[source]

End line and wait for new commands.

Return type:: None

Win32Raw

This driver uses a native WIN32 interface of Windows in order to print. Please refer to the code for documentation as this driver is currently not included in the documentation build.

class escpos.printer.Win32Raw(printer_name='', *args, **kwargs)[source]

Printer binding for win32 API.

Uses the module pywin32 for printing.

inheritance:

static is_usable()[source]

Indicate whether this printer class is usable.

Will return True if dependencies are available. Will return False if not.

Return type:: bool

__init__(printer_name='', *args, **kwargs)[source]: Initialize default printer.

property printers: dict: Available Windows printers.

open(job_name='python-escpos', raise_not_found=True)[source]

Open connection to default printer.

By default raise an exception if device is not found.

Parameters:: raise_not_found (bool) – Default True. False to log error but do not raise exception.
Raises:: DeviceNotFoundError
Return type:: None

close()[source]

Close connection to default printer.

Return type:: None