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)

USB printer.

This class describes a printer that natively speaks USB.

inheritance:

static is_usable()

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)

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)

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()

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)

Serial printer.

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

inheritance:

static is_usable()

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)

Initialize serial printer.

Parameters:

• devfile (str) – Device file under dev filesystem

• 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)

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()

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)

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()

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)

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)

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()

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)

Generic file printer.

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

inheritance:

static is_usable()

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)

Initialize file printer with device file.

Parameters:

• devfile (str) – Device file under dev filesystem

• auto_flush (bool) – automatically call flush after every call of _raw()

open(raise_not_found=True)

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()

Flush printing content.

Return type:

None

close()

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)

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()

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()

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()

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)

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()

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)

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()

Send the print job to the printer.

Return type:

None

close()

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)

Simple UNIX lp command raw printing.

Thanks to Oyami-Srk comment.

inheritance:

static is_usable()

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)

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)

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()

Stop the subprocess.

Return type:

None

flush()

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)

Printer binding for win32 API.

Uses the module pywin32 for printing.

inheritance:

static is_usable()

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)

Initialize default printer.

property printers: dict

Available Windows printers.

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

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()

Close connection to default printer.

Return type:

None