Getting started

By Alexis Rios-Negron · ThermalPrint 0.12.0

ThermalPrint is available for Debian and Ubuntu (APT), Fedora (Copr), as a Snap, and from source. All packages include the app, a desktop launcher, icons, the CUPS client tools, and Poppler PDF utilities. Updates arrive through your normal update tool.

Before you start#

You need a Linux desktop with X11 or Wayland.
Add your label printer in your desktop's printer settings (or the CUPS web page) before printing. ThermalPrint uses the printers your system already knows. It does not install drivers. A regular laser or inkjet printer works the same way: add it, then choose its paper size (such as A4 or Letter) in Print Center.
Packages are for 64-bit Intel/AMD computers (amd64 / x86_64).

Debian and Ubuntu (APT)#

The signed APT repository serves amd64 packages. Run these commands once:

sudo apt update
sudo apt install curl
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://arios4k.github.io/thermalprint/key.asc | sudo tee /etc/apt/keyrings/thermalprint.asc >/dev/null
echo 'deb [arch=amd64 signed-by=/etc/apt/keyrings/thermalprint.asc] https://arios4k.github.io/thermalprint/ stable main' | sudo tee /etc/apt/sources.list.d/thermalprint.list >/dev/null
sudo apt update
sudo apt install thermalprint

Afterwards, sudo apt update && sudo apt upgrade keeps ThermalPrint current. To install a downloaded .deb file instead, use sudo apt install ./thermalprint_*.deb so its dependencies are installed too.

Fedora (Copr)#

For Fedora 44 and 45 on x86_64, enable the community Copr repository once:

sudo dnf install dnf5-plugins
sudo dnf copr enable arios/thermalprint
sudo dnf install thermalprint

Updates arrive through normal DNF updates. Copr is a community repository and is separate from Fedora's official packages. You can also download the RPMs from the latest release.

Snap#

sudo snap install thermalprint

Snap packages update themselves. Printing connects automatically; if it ever does not, ThermalPrint shows the exact command to run. Optional extras, such as saving to USB drives, are covered in Using the Snap.

From source#

You need Rust 1.96 or newer, a C/C++ toolchain, and the usual Linux development libraries.

git clone https://github.com/arios4k/thermalprint.git
cd thermalprint
cargo run --release --locked

PDFium is optional. To use your own copy, set THERMALPRINT_PDFIUM_DIR to the folder that holds libpdfium.so. Without it, ThermalPrint renders PDFs with Poppler's pdfinfo and pdftoppm, which the packages install for you.

First launch#

Open ThermalPrint from your applications menu (or run thermalprint in a terminal).
Open Print Center and pick your printer. If the list is empty, press Refresh printers, then see Troubleshooting.
Choose the media that matches the labels you loaded, for example 4 × 6 in.
Print the alignment test if you like (details).

ThermalPrint remembers your printer, media, and other choices, separately for each printer.

Your first label#

There are two common ways to begin. Pick the one that matches what you have in front of you.

A. You have a shipping label file#

Open the label. Drag the PDF or image into the window, press Ctrl+O, or choose Add labels… in Import & Convert.
Check the crop. ThermalPrint proposes the label area. Look at the Thermal label preview, and tick I checked the crop and barcode edges when it looks right.
Pick the paper. Choose 4 × 6 in (or your stock size), your printer, and the matching media.
Print. Press Print label or Ctrl+P.

The full walk-through is in Import and Convert.

B. You want to make a label#

Open the Label Designer and choose a template on the Home screen, in File → Template gallery… (with previews), or start with a blank label.
Edit the objects. Click text to change it, drag things where you want them, and use the panel on the right for exact sizes.
Choose your printer in Print Center so the label size matches your stock.
Press Print. Save the design (Ctrl+S) if you will use it again.

See Label Designer and Objects for everything you can add, and What's new for the latest tools.

Print a test label first. A successful submission means the printer system accepted the job. It does not prove that a barcode scans. Always check the first physical label before printing a roll.

Opening saved designs by double-click#

The Debian and Fedora packages register .thermalprint files as ThermalPrint label designs, so double-clicking one opens it straight in the Label Designer, and file managers show a small preview picture of the label (from version 0.6.2; version 0.6.1 added the ThermalPrint icon). Thumbnails need a file manager that supports thumbnailers, such as Files (Nautilus), Nemo, or Caja; restart it after installing or updating. PDFs and images open in Import & Convert. Snap users can enable this with a one-time command; see Using the Snap.

Uninstalling#

Installed with	Remove with
APT	`sudo apt remove thermalprint`
Fedora	`sudo dnf remove thermalprint`
Snap	`sudo snap remove thermalprint` (add `--purge` to delete its saved data too)

Your preferences are small files in your home folder; see Settings and privacy if you want to remove them.