Cat-Printer drives cheap Bluetooth thermal printers from a browser

A BLE bridge to cheap thermal printers, not a generic print server

Cat-Printer exists because the Bluetooth thermal printers sold under names like the GB01 and the MX series ship with vendor software that is often awkward or closed. The project describes itself as supporting some Bluetooth cat printer models on many platforms, and the listed set is specific: GB01, GB02, GB03, GT01, YT01, MX05, MX06, MX08, MX10 and MXTP.

The transport is Bluetooth Low Energy through the bleak library, which the credits call the overall hero of the project, and that single dependency is the whole of requirements.txt. Everything else is the Python standard library, the web layer in the www directory, and a set of optional command line programs for talking to the printer directly.

The project entry points are visible in the repository layout. There is printer.py for direct command line control, server.py for the web interface, main.py at the root, a printer_lib directory with the shared logic, and a www directory holding the web assets and the translation files used by the interface.

The device model is open ended in a way that is worth understanding before you commit. The README says other models can be tried with the web interface through Settings and Test Unknown Device, and then adds that it may work. That is an honest statement of the state of the art here, and it is also the reason the supported model list is short.

Linux install is one script and one virtual environment

The installation instructions differ by platform, and the Linux path is the tidiest. You get the source code and run the install script to set the environment up:

sudo pacman -S bluez bluez-utils

That command is specific to Arch based distributions, where bluez may not be installed by default, and the README tells you to install it first if that applies to your system. The general Linux instruction is to run ./install.sh, and afterwards you run the server inside the virtual environment it creates:

(venv) $ python3 server.py

On macOS the shape is similar but the dependency has to be installed by hand, since the Bluetooth access on that platform needs pyobjc in addition to bleak:

pip3 install pyobjc bleak

then, from the source directory:

python3 server.py

On Windows the README asks you to download the source archive, install a recent Python, run install.bat and wait for it to finish, which leaves you with a server.bat that opens the web interface. Underneath that instruction is a comment saying the build system is broken, with an alternative of downloading a release archive whose file name contains windows and running start.bat instead. That comment is the most useful signal in the Windows section, because it tells you the source path there is known to fail.

There is also an Android route, with the newest apk release installed from the releases page, and the F-Droid repository IzzyOnDroid is described as known to include the app.

Scan time defaults are tuned per platform, not globally

Bluetooth scanning is the part of this project where the operating system matters most, and the README gives concrete defaults for each platform. On Android it recommends a scan time of 1 second, and it notes that foreground location permission is required for scanning Bluetooth devices on newer Android versions, while background location permission can be denied safely. On Windows it says scanning typically needs longer and that the default is 4 seconds, telling you to find your own case. On GNU/Linux the recommendation is 2 seconds.

Those numbers are small but they are the difference between a printer that is found immediately and one that appears after a pause, and they are a reminder that the same application behaves differently across three Bluetooth stacks.

The command line path is worth knowing about too. Once the environment is set up, the README shows the interface help output as the way to get oriented:

$ python printer.py --help

The project describes this path as the way to control the printer with a few parameters, with simplified image and text printing, and as a way to use every part of the program. The web interface remains the friendly option, but the CLI is where the parameters are exposed rather than hidden behind forms.

ImageMagick needs a policy.xml edit before pictures will print

Printing an image pulls in ImageMagick and Ghostscript, and the README is careful to say you may or may not need them depending on your distribution, and that having them is very helpful for command line work.

When they are needed, ImageMagick's own security policy blocks the operation. Because ImageMagick is built for external web servers, it applies a strict policy, and the README tells you to add a specific line to the ImageMagick policy file before the closing policymap element:

 <policy domain="coder" rights="read | write" pattern="PDM" />

The README also argues that this is safe here, on the grounds that the script is only reachable from localhost, or at most your local network. That argument is the reader's to accept, but it is worth naming the tradeoff explicitly: loosening an ImageMagick policy is a change to a security control on your machine, and the reason it is acceptable in this project is the network exposure of the web server, not the operation itself.

On a Debian style system the packages come from the usual place:

sudo apt install imagemagick ghostscript

The repository carries packaging work in progress, with a PKGBUILD file at the root, a systemd directory, and shell scripts named 0-prepare.sh and 1-build.sh that suggest a scripted build flow. The README calls that packaging work still on the way.

The web UI, the CLI and a CUPS capable server cover three audiences

The project is deliberately layered by audience. The web interface is the option for most people: it gives full control over the printer configuration, it can print a picture or run a test to check the device works, and it adapts to desktop or mobile and to light or dark themes. Accessibility features are called out as well, and translations live in the www/lang directory with the readme translated into several languages.

The command line is for people who want parameters and scripts, as described above. And the server component adds a third capability that the README lists under its extras: the server program is also CUPS and IPP capable, which means a system can treat the thermal printer as a standard print queue and print to it from any application that speaks those protocols, rather than only through the project's own interface.

That last point is what makes this more than a demo project. Once the printer is a CUPS queue, the printing problem is a solved problem on the operating system level, and the project becomes the piece that keeps the queue alive.

There is also a hosted alternative mentioned at the end of the feature list: the kitty-printer web app, for people who would rather not set the project up at all. The difference in approach is real. The web app needs no local installation and no Bluetooth access from the operating system, since the printing happens server side, but it needs your image and your content to travel to that service. The local install keeps everything on your machine and talks to the printer over your own Bluetooth connection, which is why the project insists the script is only exposed on localhost or the local network.

Licensing is split: GPL for the core files, CC0 for the rest

The licence arrangement is unusual and worth reading closely, because the summary in the repository listing would hide it.

The main files are under the GNU General Public License version 3 or later. The README names them individually: printer.py, server.py and main.js are released under GPL-3.0-or-later. The copyright line reads Copyright 2021-2024 NaitLee Soft, with some rights reserved.

Everything else, apart from parts that carry their own statements, is placed in the public domain under CC0-1.0-only. That covers the bulk of the web assets and supporting files, which is a deliberate choice to make reuse of the interface assets unrestricted while keeping the program itself copyleft.

The practical consequence for a team is straightforward. If you take the program and modify it, the GPL terms apply to your modified version of those three files. If you reuse the interface assets or documentation, you are not obliged to carry the GPL forward. Anyone packaging this inside a commercial product should read the LICENSE file and the JavaScript attribution in www/jslicense.html rather than relying on a summary.

This is a description of what the licence text says, not legal advice.

The maintainer has stepped back, and the release history shows it

The first line of the README is a notice, and it is the most important fact for an adopter: the author will no longer actively maintain Cat-Printer, and some information in the README should be treated as historical.

The repository is not archived, and the last push was on 2026-07-25, so the source is still moving even though the maintenance has stopped. The published releases tell the other half of the story. The newest is 0.6.3.0 from 2023-04-16, before that 0.6.2.1 from 2023-04-09 and 0.6.2.0 from 2023-02-12. A project whose last release is from 2023 and whose author has declared a stop is a project you adopt with different expectations: no new models will be added, no new Bluetooth stacks will be supported, and the community issue tracker is the only help available.

The remaining limitations are specific rather than general. The Windows source build is flagged as broken in the README, with release archives as the workaround. Model support is a known list with an open-ended test path that may or may not work. The ImageMagick policy edit is a required step on systems where ImageMagick is installed.

What is left is a small, readable codebase with a single dependency, a documented CLI, and a server that speaks the standard printing protocols. For anyone who has one of these printers and has already hit the wall with the vendor app, that is still worth having, as long as it is understood as a frozen tool rather than a maintained project.

Editorial conclusion

Adopt Cat-Printer if you own one of the listed Bluetooth thermal printer models and want printing without the vendor's app, and you are prepared to read the code yourself because the maintainer has stepped back. Do not adopt it if you need an actively maintained project, a confirmed model list beyond the documented ones, or a Windows build that works out of the box, since the README flags the build system as broken there. Verify first by trying Settings and Test Unknown Device in the web interface with your own model, and check the last push date against your Bluetooth stack before committing to it.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. NaitLee/Cat-Printer on GitHub
4. README
5. Releases