A command-line utility built in Python (pycups) to send files directly to your USB printer on Linux — tested on Fedora 41 with the Epson L3250 (my personal printer and OS, btw), but with cross-platform dreams.
The project was born out of personal frustration: even after installing the correct drivers, communicating with my printer and actually sending print jobs was more painful than it should be. Printing documents became a bottleneck in my workflow. So I decided to build something fast, simple, and intuitive (and customizable!) to solve it once and for all — and thus, printergeist was born.
Besides just working (hopefully), it also:
- 💅 Uses
richto make your terminal a beautiful place. - 🔍 Displays detailed technical info about the print job (format, color, size, status, etc.).
- 🧠 Features custom error messages and feedback with colorful ASCII-style emojis to make the experience fun and friendly.
- 💡 Fully hackable and extensible — feel free to play with the visuals or extend the logic.
The list above highlights a selection of representative printer models from each major brand that offer official Linux driver support. As of the latest update (2025-04-08), these models are known to be compatible with printergeist or are expected to function correctly when configured via CUPS.
This list is curated for reference and user convenience only. As a Free and Open Source Software (FOSS) project licensed under the GPLv2 License, printergeist operates independently and is not affiliated with, endorsed by, or sponsored by any of the manufacturers mentioned.
Compatibility may vary depending on the Linux distribution, driver version, and CUPS configuration. Users are encouraged to consult the official documentation of each vendor to ensure full support for advanced printing features (e.g., duplex, color modes, resolution control).
To run printergeist smoothly on your system, you'll need the following:
Python 3.9 or newer
Python dependencies:
pip install pycups rich
Before running the project, make sure CUPS is installed:
| Distribution | Package Manager | Installation Command | Enable & Start Service |
|---|---|---|---|
| Ubuntu/Debian | apt | sudo apt install cups | sudo systemctl enable --now cups |
| Fedora/RHEL/CentOS | dnf or dnf5 | sudo dnf install cups | sudo systemctl enable --now cups |
| Arch/Manjaro | pacman | sudo pacman -S cups | sudo systemctl enable --now cups |
| openSUSE | zypper | sudo zypper install cups | sudo systemctl enable --now cups |
| Alpine Linux | apk | sudo apk add cups cups-daemon | sudo rc-update add cupsd default && sudo service cupsd start |
| Gentoo | emerge | sudo emerge --ask net-print/cups | sudo rc-update add cupsd default && sudo /etc/init.d/cupsd start |
| NixOS | nixos-rebuild | services.printing.enable = true; | sudo nixos-rebuild switch |
Also make sure you have your printer drivers installed on your computer. If not, check if your printer brand is on the list below and download the available drivers for it:
| Brand | Linux Support | Driver Download Page |
|---|---|---|
| HP | ✅ Fully supported via HPLIP (HP Linux Imaging and Printing) | developers.hp.com |
| Epson | ✅ Wide support with official .deb/.rpm packages | download.ebz.epson.net |
| Brother | ✅ Supports many models via Driver Install Tool | support.brother.com |
| Canon | usa.canon.com | |
| Lexmark | ✅ Offers a Universal Print Driver for Linux | support.lexmark.com |
| Samsung | samsungsetup.com | |
| Xerox | ✅ Provides Linux-compatible drivers and PPDs | support.xerox.com |
| Ricoh | ✅ Universal drivers for many models | support.ricoh.com |
| Kyocera | ✅ Good Linux support with documentation | kyoceradocumentsolutions.us |
| Dell | dell.com |
After reviewing the project requirements and ensuring all dependencies are properly installed, you can proceed by cloning this repository:
git clone https://github.com/mvghasty/printergeist.gitOnce the repository is cloned, navigate to the application directory and run the main script:
cd printergeist/src
python main.pyAlternatively, you can create a binary-like executable using the pgeist bash script located in the src/ directory. This allows you to run the program from anywhere as a CLI tool.
1. Open the pgeist file in your preferred text editor:
emacs pgeist # or use nano, vim, code, etc.2. Locate the following line:
PATH_PGT="path/to/main.py"3. Replace "path/to/main.py" with the absolute or relative path to the main.py file inside the printergeist/src directory.
4. Save the file and execute it. The script will automatically handle the installation and move the executable to the /usr/local/bin directory, making it accessible system-wide as pgeist.
The source code is thoroughly documented. If you have any questions about implementation details or internal logic, please refer to the inline comments within the codebase.