{"id":7553,"library":"pycups","title":"PyCUPS - Python CUPS Bindings","description":"PyCUPS provides Python bindings for libcups, the Common Unix Printing System library. It allows Python applications to interact with CUPS servers to manage printers, print jobs, and monitor printer status. The current version is 2.0.4, with releases primarily focusing on bug fixes and compatibility with newer Python versions, rather than new features.","status":"active","version":"2.0.4","language":"en","source_language":"en","source_url":"https://github.com/OpenPrinting/pycups","tags":["cups","printing","linux","system","bindings"],"install":[{"cmd":"pip install pycups","lang":"bash","label":"Install PyCUPS"}],"dependencies":[{"reason":"Requires development headers for the CUPS library (e.g., `libcups2-dev` on Debian/Ubuntu, `cups-devel` on Fedora/RHEL) to compile the C extensions during installation.","package":"libcups-dev","optional":false}],"imports":[{"symbol":"cups","correct":"import cups"}],"quickstart":{"code":"import cups\n\n# Connect to the local CUPS server\nconn = cups.Connection()\n\n# List all available printers\nprinters = conn.getPrinters()\n\nif printers:\n    print(\"Available Printers:\")\n    for printer_name, printer_attrs in printers.items():\n        print(f\"  - {printer_name}\")\n        # print(f\"    Location: {printer_attrs.get('printer-location')}\")\n        # print(f\"    State: {printer_attrs.get('printer-state-message')}\")\nelse:\n    print(\"No printers found or CUPS server is not accessible.\")\n\n# Example: Get default printer (if set)\ndefault_printer = conn.getDefault() # Returns string or None\nif default_printer:\n    print(f\"\\nDefault Printer: {default_printer}\")\n","lang":"python","description":"This quickstart demonstrates how to establish a connection to the local CUPS server and list all configured printers. It's a common first step to verify PyCUPS installation and CUPS server connectivity."},"warnings":[{"fix":"Install the necessary CUPS development package for your operating system (e.g., `sudo apt-get install libcups2-dev` or `sudo dnf install cups-devel`).","message":"PyCUPS requires system-level CUPS development headers (e.g., `libcups2-dev` on Debian/Ubuntu, `cups-devel` on Fedora/RHEL) to be installed on the system *before* `pip install pycups`. Without these, the installation will fail with compilation errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the CUPS service is running on your system (e.g., `sudo systemctl status cups` on systemd-based Linux distributions) and that appropriate firewall rules allow access if connecting remotely.","message":"Many functions in PyCUPS interact directly with the CUPS server. If the CUPS service is not running or accessible, operations like `cups.Connection()` or `conn.getPrinters()` will raise `cups.IPPError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all strings passed to PyCUPS functions are correctly encoded, typically to UTF-8. Decode received byte strings from CUPS if you encounter `UnicodeDecodeError` or unexpected characters.","message":"When handling IPP attributes (like printer names, job titles) with non-ASCII characters, be mindful of encoding. While PyCUPS aims to handle UTF-8, explicit encoding/decoding may be necessary for certain operations or when integrating with other systems.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"First, ensure pycups is installed: `pip install pycups`. If the error persists, it's likely due to missing system-level CUPS development headers. Install them (e.g., `sudo apt-get install libcups2-dev` on Debian/Ubuntu) and then reinstall pycups.","cause":"The 'cups' module could not be found, either because pycups was not installed or its C extensions failed to compile.","error":"ModuleNotFoundError: No module named 'cups'"},{"fix":"Upgrade pycups to version 2.0.3 or newer, which includes a fix by defining `PY_SSIZE_T_CLEAN` to ensure correct type handling for Python 3.10+.","cause":"This specific error often occurred with Python 3.10 due to changes in C API handling of `Py_ssize_t` causing type mismatches during IPP request/response processing.","error":"TypeError: an integer is required (got type bytes) in method 'IPPRequest_writeIO'"},{"fix":"Check the CUPS server status (`sudo systemctl status cups`). Verify the printer name/URI is correct. Ensure the user running the Python script has appropriate permissions to access the CUPS server and printers.","cause":"This is a generic CUPS IPP error indicating 'bad request' or similar. Common reasons include the CUPS server not being reachable, a printer not existing, incorrect printer URI, or authentication failure.","error":"cups.IPPError: 1007"}]}