Module escpos.escpos

Main class

This module contains the abstract base class Escpos.

author:Manuel F Martinez and others
organization:Bashlinux and python-escpos
copyright:Copyright (c) 2012 Bashlinux
license:GNU GPL v3
class escpos.escpos.Escpos(columns=32)

Bases: object

ESC/POS Printer object

This class is the abstract base class for an esc/pos-printer. The printer implementations are children of this class.

barcode(code, bc, height=64, width=3, pos=u'BELOW', font=u'A', align_ct=True, function_type=u'A')

Print Barcode

This method allows to print barcodes. The rendering of the barcode is done by the printer and therefore has to be supported by the unit. Currently you have to check manually whether your barcode text is correct. Uncorrect barcodes may lead to unexpected printer behaviour. There are two forms of the barcode function. Type A is default but has fewer barcodes, while type B has some more to choose from.


Add a method to check barcode codes. Alternatively or as an addition write explanations about each barcode-type. Research whether the check digits can be computed autmatically.

Use the parameters height and width for adjusting of the barcode size. Please take notice that the barcode will not be printed if it is outside of the printable area. (Which should be impossible with this method, so this information is probably more useful for debugging purposes.)


On TM-T88II width from 1 to 6 is accepted. Try to acquire command reference and correct the code.


Supplying pos does not have an effect for every barcode type. Check and document for which types this is true.

If you do not want to center the barcode you can call the method with align_ct=False, which will disable automatic centering. Please note that when you use center alignment, then the alignment of text will be changed automatically to centered. You have to manually restore the alignment if necessary.


If further barcode-types are needed they could be rendered transparently as an image. (This could also be of help if the printer does not support types that others do.)

  • code – alphanumeric data to be printed as bar code
  • bc

    barcode format, possible values are for type A are:

    • UPC-A
    • UPC-E
    • EAN13
    • EAN8
    • CODE39
    • ITF
    • NW7

    Possible values for type B:

    • All types from function type A
    • CODE93
    • CODE128
    • GS1-128
    • GS1 DataBar Omnidirectional
    • GS1 DataBar Truncated
    • GS1 DataBar Limited
    • GS1 DataBar Expanded

    If none is specified, the method raises BarcodeTypeError.

  • height (int) – barcode height, has to be between 1 and 255 default: 64
  • width (int) – barcode width, has to be between 2 and 6 default: 3
  • pos

    where to place the text relative to the barcode, default: BELOW

    • ABOVE
    • BELOW
    • BOTH
    • OFF
  • font

    select font (see ESC/POS-documentation, the device often has two fonts), default: A

    • A
    • B
  • align_ct (bool) – If this parameter is True the barcode will be centered. Otherwise no alignment command will be issued.
  • function_type – Choose between ESCPOS function type A or B, depending on printer support and desired barcode. default: A

BarcodeSizeError, BarcodeTypeError, BarcodeCodeError

block_text(txt, columns=None)

Text is printed wrapped to specified columns

Text has to be encoded in unicode.

  • txt – text to be printed
  • columns – amount of columns



Send pulse to kick the cash drawer

Kick cash drawer on pin 2 or pin 5 according to parameter.

Parameters:pin – pin number, 2 or 5

Set Character Code Table

Sends the control sequence from escpos.constants to the printer with escpos.printer.'implementation'._raw().

Parameters:code – Name of CharCode
codepage = None
control(ctl, pos=4)

Feed control sequences

  • ctl

    string for the following control sequences:

    • LF for Line Feed
    • FF for Form Feed
    • CR for Carriage Return
    • HT for Horizontal Tab
    • VT for Vertical Tab
  • pos – integer between 1 and 16, controls the horizontal tab position



Cut paper.

Without any arguments the paper will be cut completely. With ‘mode=PART’ a partial cut will be attempted. Note however, that not all models can do a partial cut. See the documentation of your printer for details.


Check this function on TM-T88II.

Parameters:mode – set to ‘PART’ for a partial cut
device = None

Hardware operations


hardware action, may be:

  • INIT
image(img_source, high_density_vertical=True, high_density_horizontal=True, impl=u'bitImageRaster', fragment_height=1024)

Print an image

You can select whether the printer should print in high density or not. The default value is high density. When printing in low density, the image will be stretched.

Esc/Pos supplies several commands for printing. This function supports three of them. Please try to vary the implementations if you have any problems. For example the printer IT80-002 will have trouble aligning images that are not printed in Column-mode.

The available printing implementations are:

  • bitImageRaster: prints with the GS v 0-command
  • graphics: prints with the GS ( L-command
  • bitImageColumn: prints with the ESC *-command
  • img_source – PIL image or filename to load: jpg, gif, png or bmp
  • high_density_vertical – print in high density in vertical direction default: True
  • high_density_horizontal – print in high density in horizontal direction default: True
  • impl – choose image printing mode between bitImageRaster, graphics or bitImageColumn
  • fragment_height – Images larger than this will be split into multiple fragments default: 1024
line_spacing(spacing=None, divisor=180)

Set line character spacing.

If no spacing is given, we reset it to the default.

There are different commands for setting the line spacing, using a different denominator:

‘+’’ line_spacing/360 of an inch, 0 <= line_spacing <= 255 ‘3’ line_spacing/180 of an inch, 0 <= line_spacing <= 255 ‘A’ line_spacing/60 of an inch, 0 <= line_spacing <= 85

Some printers may not support all of them. The most commonly available command (using a divisor of 180) is chosen.


Controls the panel buttons on the printer (e.g. FEED)

When enable is set to False the panel buttons on the printer will be disabled. Calling the method with enable=True or without argument will enable the panel buttons.

If panel buttons are enabled, the function of the panel button, such as feeding, will be executed upon pressing the button. If the panel buttons are disabled, pressing them will not have any effect.

This command is effective until the printer is initialized, reset or power-cycled. The default is enabled panel buttons.

Some panel buttons will always work, especially when printer is opened. See for more information the manual of your printer and the escpos-command-reference.

Parameters:enable – controls the panel buttons
Return type:None
qr(content, ec=0, size=3, model=2, native=False)

Print QR Code for the provided string

  • content – The content of the code. Numeric data will be more efficiently compacted.
  • ec – Error-correction level to use. One of QR_ECLEVEL_L (default), QR_ECLEVEL_M, QR_ECLEVEL_Q or QR_ECLEVEL_H. Higher error correction results in a less compact code.
  • size – Pixel size to use. Must be 1-16 (default 3)
  • model – QR code model to use. Must be one of QR_MODEL_1, QR_MODEL_2 (default) or QR_MICRO (not supported by all printers).
  • native – True to render the code on the printer, False to render the code as an image and send it to the printer (Default)
set(align=u'left', font=u'a', text_type=u'normal', width=1, height=1, density=9, invert=False, smooth=False, flip=False)

Set text properties by sending them to the printer

  • align

    horizontal position for text, possible values are:

    • CENTER
    • LEFT
    • RIGHT

    default: LEFT

  • font – font type, possible values are A or B, default: A
  • text_type

    text type, possible values are:

    • B for bold
    • U for underlined
    • U2 for underlined, version 2
    • BU for bold and underlined
    • BU2 for bold and underlined, version 2
    • NORMAL for normal text

    default: NORMAL

  • width – text width multiplier, decimal range 1-8, default: 1
  • height – text height multiplier, decimal range 1-8, default: 1
  • density – print density, value from 0-8, if something else is supplied the density remains unchanged
  • invert (bool) – True enables white on black printing, default: False
  • smooth – True enables text smoothing. Effective on 4x4 size text and larger, default: False
  • flip – True enables upside-down printing, default: False

Print alpha-numeric text

The text has to be encoded in the currently selected codepage. The input text has to be encoded in unicode.

Parameters:txt – text to be printed
class escpos.escpos.EscposIO(printer, autocut=True, autoclose=True, **kwargs)

Bases: object

ESC/POS Printer IO object

Allows the class to be used together with the with-statement. You have to define a printer instance and assign it to the EsposIO-class. This example explains the usage:

with EscposIO(printer.Serial('/dev/ttyUSB0')) as p:
    p.set(font='a', height=2, align='center', text_type='bold')
    p.writelines('Big line\n', font='b')
    p.writelines('BIG TEXT', width=2)

After the with-statement the printer automatically cuts the paper if autocut is True.


called upon closing the with-statement


Set the printer-parameters

Controls which parameters will be passed to Escpos.set(). For more information on the parameters see the set()-methods documentation. These parameters can also be passed with this class’ constructor or the writelines()-method.

Parameters:kwargs – keyword-parameters that will be passed to Escpos.set()
writelines(text, **kwargs)