ESC/POS Rust implementation

This crate implements a subset of Epson's ESC/POS protocol for thermal receipt printers. It allows you to generate and print documents with basic text formatting, cutting, barcodes, QR codes and raster images on a compatible printer. It also provides a way to check the printer status.

Printed on Aures ODP 333

This project is strongly inspired by recibo (Rust), escposify (Rust) and escpos (Go).

Installation

For standard functionalities (e.g., printing text), no additional dependencies are required:

[dependencies]
escpos = "0.19.0"

If you need all features, you can use the full feature:

[dependencies]
escpos = { version = "0.19.0", features = ["full"] }

Or you can use cargo add command:

cargo add escpos
cargo add escpos -F full

Code coverage

Tool used: tarpaulin

cargo install cargo-tarpaulin

cargo tarpaulin --all-features --tests

Results:

• [2025-09-15] 57.62% coverage, 1172/2034 lines covered

MSRV

Tool used: cargo-msrv

cargo install cargo-msrv

cargo msrv find
cargo msrv verify

Features list

no_std support

The crate can be used on bare-metal targets (microcontrollers, kernels…) by disabling default features. Only alloc is required:

[dependencies]
escpos = { version = "0.18", default-features = false, features = ["barcodes", "codes_2d"] }

The built-in Console, Network and File drivers as well as the graphics feature require std. In no_std mode you implement the Driver trait for your peripheral (UART, SPI, USB endpoint, …) and pass it to Printer::new. The Printer::driver accessor lets you recover the driver from a Printer.

See examples/no_std_codes.rs for a minimal example with a custom in-memory driver and barcodes / 2D codes — all the protocol-level APIs (barcodes, QR Code, PDF417, DataMatrix, Aztec, MaxiCode, page codes, status…) work in no_std. The codes themselves are rendered by the printer's firmware: the crate only serializes the ESC/POS commands, so the embedded-side cost is minimal.

Examples

The examples folder contains various examples of how to use escpos.
The docs also provide code snippets and examples.

To launch an example, use the following command:

RUST_LOG=debug cargo run --example full --features full

The list of all the examples can be found here.

Simple text formatting

use escpos::printer::Printer;
use escpos::printer_options::PrinterOptions;
use escpos::utils::*;
use escpos::{driver::*, errors::Result};

fn main() -> Result<()> {
    env_logger::init();

    let driver = NetworkDriver::open("192.168.1.248", 9100, None)?;
    Printer::new(driver, Protocol::default(), Some(PrinterOptions::default()))
        .debug_mode(Some(DebugMode::Dec))
        .init()?
        .smoothing(true)?
        .bold(true)?
        .underline(UnderlineMode::Single)?
        .writeln("Bold underline")?
        .justify(JustifyMode::CENTER)?
        .reverse(true)?
        .bold(false)?
        .writeln("Hello world - Reverse")?
        .feed()?
        .justify(JustifyMode::RIGHT)?
        .reverse(false)?
        .underline(UnderlineMode::None)?
        .size(2, 3)?
        .writeln("Hello world - Normal")?
        .print_cut()?; // print() or print_cut() is mandatory to send the data to the printer

    Ok(())
}

EAN13

use escpos::printer::Printer;
use escpos::utils::*;
use escpos::{driver::*, errors::Result};

fn main() -> Result<()> {
    env_logger::init();

    let driver = ConsoleDriver::open(true);
    Printer::new(driver, Protocol::default(), None)
        .debug_mode(Some(DebugMode::Hex))
        .init()?
        .ean13_option(
            "1234567890265",
            BarcodeOption::new(
                BarcodeWidth::M,
                BarcodeHeight::S,
                BarcodeFont::A,
                BarcodePosition::Below,
            )
        )?
        .feed()?
        .print()?; // print() or print_cut() is mandatory to send the data to the printer
    Ok(())
}

QR Code

use escpos::printer::Printer;
use escpos::utils::*;
use escpos::{driver::*, errors::Result};

fn main() -> Result<()> {
    env_logger::init();

    let driver = ConsoleDriver::open(true);
    Printer::new(driver, Protocol::default(), None)
        .debug_mode(Some(DebugMode::Hex))
        .init()?
        .qrcode_option(
            "https://www.google.com",
            QRCodeOption::new(QRCodeModel::Model1, 6, QRCodeCorrectionLevel::M),
        )?
        .feed()?
        .print_cut()?; // print() or print_cut() is mandatory to send the data to the printer

    Ok(())
}

Bit image (with graphics feature enabled)

use escpos::printer::Printer;
use escpos::utils::*;
use escpos::{driver::*, errors::Result};

fn main() -> Result<()> {
    env_logger::init();

    let driver = ConsoleDriver::open(true);
    let mut printer = Printer::new(driver, Protocol::default(), None);
    printer.debug_mode(Some(DebugMode::Hex))
        .init()?
        .bit_image_option(
            "./resources/images/rust-logo-small.png",
            BitImageOption::new(Some(128), None, BitImageSize::Normal)?,
        )?
        .feed()?
        .print_cut()?; // print() or print_cut() is mandatory to send the data to the printer

    Ok(())
}

Windows USB print driver (with usbprint feature enabled, Windows only)

Drives a POS printer through the standard Windows usbprint.sys kernel driver using the Win32 API (CreateFile / ReadFile / WriteFile). No Zadig / WinUSB / libusb swap required — the device keeps working with the regular Windows print spooler at the same time.

use escpos::printer::Printer;
use escpos::utils::*;
use escpos::{driver::*, errors::Result};

fn main() -> Result<()> {
    env_logger::init();

    // List USB printers exposed by usbprint.sys
    for info in WindowsUsbPrintDriver::list()? {
        println!("{} (VID={:?} PID={:?})", info.device_path, info.vendor_id, info.product_id);
    }

    // Option 1: open by USB vendor/product id
    let driver = WindowsUsbPrintDriver::open_by_vid_pid(0x0525, 0xa700)?;

    // Option 2: open by full device interface path
    // let driver = WindowsUsbPrintDriver::open(r"\\?\USB#VID_0525&PID_A700#...")?;

    Printer::new(driver, Protocol::default(), None)
        .init()?
        .writeln("Hello from Windows usbprint!")?
        .print_cut()?;

    Ok(())
}

Check printer status

use escpos::printer::Printer;
use escpos::utils::*;
use escpos::{driver::*, errors::Result};

fn main() -> Result<()> {
    env_logger::init();

    let driver = ConsoleDriver::open(true);
    Printer::new(driver.clone(), Protocol::default(), None)
        .debug_mode(Some(DebugMode::Dec))
        .real_time_status(RealTimeStatusRequest::Printer)?
        .real_time_status(RealTimeStatusRequest::RollPaperSensor)?
        .send_status()?;

    let mut buf = [0; 1];
    driver.read(&mut buf)?;

    let status = RealTimeStatusResponse::parse(RealTimeStatusRequest::Printer, buf[0])?;
    println!(
        "Printer online: {}",
        status.get(&RealTimeStatusResponse::Online).unwrap_or(&false)
    );

    Ok(())
}

Commands list

• ✅ Done
• 🚧 In progress
• ❌ To do

Page codes list

External resources

• Epson documentation