Raw Printing
Raw Printing allows ERPNext to send printer commands directly to compatible printers in their native language, bypassing traditional printer drivers.
Raw Printing is ideal for thermal printers used for receipts, labels, barcodes, and other specialized printing tasks where speed and precision are essential.
Unlike standard PDF or HTML printing, Raw Printing transmits command strings directly to the printer, enabling advanced hardware features such as automatic paper cutting, barcode generation, and cash drawer control.
Prerequisites
Before using Raw Printing, ensure the following requirements are met:
- A compatible thermal printer that supports raw printer commands.
- QZ Tray installed on the client computer connected to the printer.
- Java installed if required during QZ Tray installation.
- Knowledge of your printer’s native command language (such as ESC/POS, ZPL, EPL, etc.).
Step 1: Install QZ Tray
QZ Tray acts as the communication bridge between ERPNext and the locally connected printer.
- Download and install QZ Tray on the client computer.
- Complete the installation process.
- Install Java if prompted during setup.
- Ensure QZ Tray is running before attempting Raw Printing.
Raw Printing requires QZ Tray to establish secure communication between the browser and the printer.
Step 2: Create a Raw Print Format
Raw Printing requires a custom Print Format that contains the printer’s native commands.
- Go to Home → Settings → Printing → Print Format.
- Create a new Print Format.
- Select the required DocType.
- Enable Custom Format.
- Enable Raw Printing.
- Enter the printer commands in the Raw Commands field.
- Save the Print Format.
The Raw Commands field supports Jinja templating, allowing document values to be dynamically inserted into printer commands.
Raw Commands must be written in the printer’s native command language provided by the printer manufacturer.
Step 3: Enable Raw Printing
Navigate to:
Home → Settings → Printing → Print Settings → Raw Printing- Enable Raw Printing.
- Save the settings.
Methods to Use Raw Printing
Method 1: Print from a Document
- Open the required document.
- Select the Raw Print Format.
- Click Print.
- Allow the QZ Tray connection request.
- Select the printer if prompted.
Since raw commands cannot be rendered visually, the print preview displays a message indicating that no preview is available.
ERPNext stores the mapping between a Print Format and a printer locally on each client machine.
Printer mappings are stored locally, so each client computer must configure its own printer association.
Method 2: Trigger Raw Printing Using Client Scripts
Raw Printing can also be automated using Client Scripts. This is useful when printing should occur automatically after actions such as saving or submitting a document.
Common Raw Printing helper functions include:
- frappe.ui.form.qz_connect — Establishes a connection with QZ Tray.
- frappe.ui.form.qz_get_printer_list — Returns the list of available printers.
- frappe.ui.form.qz_success — Displays a success notification after printing.
- frappe.ui.form.qz_fail — Displays connection or printing errors.
After a successful connection, the global qz object can be used to access additional QZ Tray functions for advanced printing operations.
Common Use Cases
- Receipt printing on POS thermal printers.
- Barcode label printing.
- Shipping label generation.
- Warehouse labeling.
- Kitchen Order Ticket (KOT) printing.
- Automatic cash drawer opening.
- Automatic receipt paper cutting.
Benefits of Raw Printing
- Very fast printing with minimal processing.
- Bypasses printer drivers for improved reliability.
- Supports advanced printer-specific features.
- Works with barcode and label printers.
- Can be automated using Client Scripts.
- Supports dynamic document data using Jinja templates.
Best Practices
- Keep QZ Tray running while using Raw Printing.
- Test raw commands with sample documents before production use.
- Refer to your printer manufacturer’s command reference when creating templates.
- Create separate Raw Print Formats for different printer models if required.
- Configure printer mappings individually on every client computer.
