python-escpos：用 Python 控制 ESC/POS 印表機，從 USB 到網路都包辦
用於操作 ESC/POS 印表機的 Python 庫。 python-escpos - 用於操作 ESC/POS 印表機的 Python 庫 描述 =========== ..
秒懂
- 它是什麼？
- python-escpos 是一套純 Python 的 ESC/POS 印表機操作函式庫，涵蓋 USB、序列與網路連線，並以 profile 機制對應不同機型。本文檢視它的實際用法、依賴與限制，判斷哪些專案該用、哪些不該用。
- 適合誰用？
- 若你的專案需要從 Python 直接驅動 ESC/POS 印表機，而且能接受 pyusb、pyserial 等底層依賴，python-escpos 是少數同時涵蓋 USB、序列與網路三種介面的選擇。它適合 POS 系統、出單程式、小型工具腳本。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 1 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月14日）與我們的分析，不構成法律意見。
開源專案深度解析
它解決什麼問題，誰需要它
ESC/POS 是 Epson 定義的一組印表機控制指令，廣泛用於收據機、標籤機與廚房出單機。直接對印表機送指令不是不行，但要處理文字編碼、影像轉換、條碼格式、紙張裁切等細節，每個機型又可能略有差異。python-escpos 把這些包成一層 Python API，讓開發者用 p.text()、p.barcode()、p.cut() 就能完成常見操作。這套函式庫主要服務的對象是寫 POS 系統、自動化出單、或需要從 Python 程式控制實體印表機的工程師。它不是一個列印伺服器，也不是圖形化工具，它就是一個函式庫，你得自己寫呼叫它的程式。
三種連線方式，一個 API 表面
python-escpos 提供 Usb、Network、Serial 三個印表機類別，分別對應 USB、乙太網路與序列埠。三者的用法一致，差別只在初始化參數。USB 連線需要指定 vendor ID 與 product ID，範例中是 0x04b8 與 0x0202，對應 Epson TM-T88III。Network 連線只需 IP 位址，例如 kitchen = Network("192.168.1.100", profile="TM-T88III")。Serial 連線則要指定裝置檔、baudrate、bytesize 等參數，範例使用 9600 baud、8N1、啟用 dsrdtr。這種設計讓同一套業務邏輯可以套用在不同連線方式，只要換掉初始化那行。但要注意，USB 連線依賴 pyusb，這在 Linux 上通常需要 root 權限或 udev 規則，Windows 上則要安裝對應的 USB 驅動。文件沒有提到這點，但這是 pyusb 的已知特性。
profile 機制是關鍵，也是風險
ESC/POS 指令在不同印表機上並非完全一致，python-escpos 透過 profile 參數來對應機型能力。文件特別強調「強烈建議」包含匹配的 profile，因為這會告知函式庫該印表機支援哪些功能。profile 由 escpos-printer-db 這個外部專案管理，它同時也被 escpos-php 使用。這意味著 profile 的維護責任不在 python-escpos 本身，而是依賴另一個專案。如果你的印表機型號不在資料庫中，你就得自己測試哪些指令有效、哪些無效。這是一個實際的風險點：profile 不完整時，函式庫可能送出印表機不支援的指令，導致亂碼或無反應。文件沒有提供 profile 的查詢方式，但你可以去 escpos-printer-db 的 GitHub 頁面找。
實際跑起來：從安裝到印出第一行文字
安裝方式文件沒有明說，但從依賴列表推測，pip install python-escpos 會一併帶上 pyusb、Pillow、qrcode、pyserial、python-barcode。基本用法很直接，先 import 對應的 printer 類別，建立實例，然後呼叫方法。以 USB 為例：p = Usb(0x04b8, 0x0202, 0, profile="TM-T88III")，接著 p.text("Hello World\n") 送出文字，p.image("logo.gif") 列印圖片，p.barcode('4006381333931', 'EAN13', 64, 2, '', '') 印條碼，最後 p.cut() 裁紙。Network 與 Serial 的範例也類似，差別只在建立實例的參數。QR code 的用法在 Serial 範例中出現：p.qr("You can readme from your smartphone")。整體 API 設計很簡潔，學習成本低。但要注意，image() 方法接受的是檔案路徑，不是 PIL Image 物件，這點從範例看不出來，文件可能另有說明。
依賴套件是雙面刃
python-escpos 依賴五個套件：pyusb 處理 USB、pyserial 處理序列、Pillow 處理影像、qrcode 產生 QR code、python-barcode 產生條碼。這代表安裝時會拉進不少東西，但每個依賴都有其必要性。問題在於這些依賴的維護狀態不一，例如 pyusb 與 pyserial 都是成熟的專案，但 python-barcode 的更新頻率可能較低。另外，Pillow 是影像處理的重型套件，如果你只需要文字與條碼，它可能顯得過重。從維護角度來看，python-escpos 本身最後一次釋出是 2023 年 12 月的 v3.1，距今已有一段時間。依賴套件若有安全更新或 Python 版本相容性問題，你得自己追蹤。License 是 MIT，這對商業使用友善，但請自行確認依賴套件的授權條款，因為 pyusb 是 Apache 2.0，Pillow 是 MIT-CMU，qrcode 是 MIT，pyserial 是 BSD，python-barcode 是 MIT，混用時要注意授權相容性，這不是法律建議，只是提醒。
限制與失敗模式
最大的限制是印表機相容性完全依賴 profile。文件說「支援的指令因印表機而異」，這表示你無法假設每個指令都能用。例如某些低價標籤機可能不支援 QR code，或裁紙指令的參數不同。另一個限制是 USB 連線的系統依賴，pyusb 在沒有適當權限的環境下會直接失敗，這在 Docker 容器或 CI 環境中尤其麻煩。Network 連線相對單純，但文件沒有提到逾時處理或重連機制，如果你的印表機離線，Network 實例可能拋出異常，你得自己處理。此外，image() 方法依賴 Pillow，但文件沒有說明支援哪些圖片格式，實際使用時可能需要先轉檔。這些都是採用前要驗證的項目，尤其是印表機型號不在 escpos-printer-db 中的情況。
替代方案：直接送指令或換語言
如果你只需要網路印表機，其實可以跳過這個函式庫，直接用 Python 的 socket 連到印表機的 9100 埠，然後送出 ESC/POS 原始指令。這樣做的好處是零依賴，壞處是你得自己處理指令細節與編碼。另一種替代是 escpos-php，它同樣使用 escpos-printer-db，但語言是 PHP，適合已經用 PHP 寫後端的專案。escpos-php 與 python-escpos 的差異在於語言生態，而不是功能。若你的專案用 Python，而且需要多種連線方式，python-escpos 是現成的選擇；若只需要網路，自製 socket 程式碼可能更輕量。比較時要考慮的是你願意維護多少底層細節，而不是哪個函式庫比較「強大」。
維護成本與升級考量
從釋出時間看，v3.0 在 2023 年 11 月，v3.1 在 2023 年 12 月，間隔一個月，顯示 v3.0 可能有一些修正。但之後就沒有新版本，這不代表專案死了，只是維護節奏慢。升級時要注意 v3.0 是主要版本，可能有不兼容變更，但文件沒有列出 changelog，你必須自己看 GitHub releases。採用這個函式庫，維護成本主要來自三方面：追蹤依賴套件更新、確認 profile 與印表機型號的匹配、以及處理不同作業系統的 USB 權限問題。如果你能接受這些，python-escpos 是可行的；如果不能，找一個更活躍的專案或自己寫 socket 層可能更省事。
編輯結論
若你的專案需要從 Python 直接驅動 ESC/POS 印表機，而且能接受 pyusb、pyserial 等底層依賴，python-escpos 是少數同時涵蓋 USB、序列與網路三種介面的選擇。它適合 POS 系統、出單程式、小型工具腳本。若你只需要網路印表機，或想避開 USB 權限與驅動問題，可以考慮直接用 socket 送 ESC/POS 指令，或改用 escpos-php 那類專注單一介面的函式庫。採用前，先確認你的印表機型號有對應的 profile，若沒有，必須自行測試指令相容性。另外，最後一次釋出是 2023 年 12 月的 v3.1，若你的 Python 版本較新，先檢查 pyusb 與 Pillow 是否相容，再決定是否採用。
社群筆記