diff --git a/README.md b/README.md
index d7eff4b..26cf14d 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,15 @@ pip install oss-harmony
 uv pip install oss-harmony
 ```
 
+> **Note:** `oss-harmony` and `openai-harmony` both provide the `openai_harmony` Python
+> module. Do not install both packages in the same environment — pip will silently
+> overwrite one with the other. If you are switching between packages, uninstall the
+> existing one first:
+>
+> ```bash
+> pip uninstall openai-harmony && pip install oss-harmony
+> ```
+
 #### Example
 
 ```python
diff --git a/docs/python.md b/docs/python.md
index 85ea062..d3e17c8 100644
--- a/docs/python.md
+++ b/docs/python.md
@@ -10,6 +10,15 @@ Install the package from PyPI:
 pip install oss-harmony
 ```
 
+> **Note:** `oss-harmony` and `openai-harmony` both provide the `openai_harmony` Python
+> module. Do not install both packages in the same environment — pip will silently
+> overwrite one with the other. If you are switching between packages, uninstall the
+> existing one first:
+>
+> ```bash
+> pip uninstall openai-harmony && pip install oss-harmony
+> ```
+
 Typical imports look like:
 
 ```python