diff --git a/README.md b/README.md
index fb7056a..cfe609e 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,22 @@ If you want optional large-image extras:
 uv sync --extra large-images
 ```
 
+## Migration note
+
+The import path has been renamed from `googleart_download` to `artx`.
+
+- `googleart_download` remains as a compatibility shim for two minor releases
+- it emits a `DeprecationWarning` on import
+- if you use this project as a library, update your imports:
+
+```python
+# Old
+from googleart_download import ...
+
+# New
+from artx import ...
+```
+
 ## Quick Start
 
 Download one artwork:
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
index 6ff75dc..a23fc31 100644
--- a/docs/README.zh-CN.md
+++ b/docs/README.zh-CN.md
@@ -57,6 +57,22 @@ uv run artx --help
 uv sync --extra large-images
 ```
 
+## 迁移说明
+
+库导入路径已从 `googleart_download` 更名为 `artx`。
+
+- 旧的 `googleart_download` 作为兼容层保留两个小版本
+- 导入旧包会发出 `DeprecationWarning`
+- 如果你把本项目作为库使用，请将导入改为 `artx`
+
+```python
+# 旧
+from googleart_download import ...
+
+# 新
+from artx import ...
+```
+
 ## 快速开始
 
 下载一张作品：
diff --git a/docs/usage.md b/docs/usage.md
index 1bff825..54d3986 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -1,5 +1,21 @@
 # Usage
 
+## Migration note
+
+The library import path changed: `googleart_download` → `artx`.
+
+- The old `googleart_download` package remains as a forwarder for two minor versions
+- Importing it will emit a `DeprecationWarning`
+- If you embed this project as a library, switch your imports to `artx`
+
+```python
+# before
+from googleart_download import ...
+
+# after
+from artx import ...
+```
+
 ## Basic Download
 
 ```bash