From 3aaf54f661e4352c32538065cd003e6f86e7b43c Mon Sep 17 00:00:00 2001
From: Mirochill <200482516+Mirochill@users.noreply.github.com>
Date: Mon, 25 May 2026 22:03:23 +0200
Subject: [PATCH] docs: clarify package name for installation

---
 CHANGELOG.rst             |  2 ++
 doc/user/installation.rst | 10 ++++++++++
 2 files changed, 12 insertions(+)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 1804bb38..9610acf8 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -8,6 +8,8 @@ Changelog
 changes
 ^^^^^^^
 
+- document that the package should be installed as ``python-escpos``, not the
+  unrelated ``escpos`` package
 
 contributors
 ^^^^^^^^^^^^
diff --git a/doc/user/installation.rst b/doc/user/installation.rst
index 64079c8c..9b821507 100644
--- a/doc/user/installation.rst
+++ b/doc/user/installation.rst
@@ -21,6 +21,16 @@ always install from PyPi.
 If you use the ``--pre`` parameter for ``pip``, you will get the latest
 pre-release.
 
+.. note::
+
+   The PyPI package name is ``python-escpos``. The unrelated and discontinued
+   package named ``escpos`` uses the same ``escpos`` import namespace and can
+   shadow python-escpos if both are installed in the same environment. If an
+   import such as ``from escpos.printer import Usb`` fails with
+   ``ImportError: cannot import name 'DeviceNotFoundError' from
+   'escpos.exceptions'``, remove the ``escpos`` package and reinstall
+   ``python-escpos`` in a clean environment.
+
 The following installation options exist:
 
  * `all`: install all packages available for this platform