diff --git a/README.md b/README.md
index 9afc7f4f7..47769ab91 100644
--- a/README.md
+++ b/README.md
@@ -104,6 +104,9 @@ For full installation instructions, including verification and upgrading, see th
 - [Upgrading from the MCP Python SDK](https://gofastmcp.com/getting-started/upgrading/from-mcp-sdk)
 - [Upgrading from the low-level SDK](https://gofastmcp.com/getting-started/upgrading/from-low-level-sdk)
 
+> [!NOTE]
+> If `import fastmcp` fails right after a `pip` upgrade from FastMCP 3.2 or earlier, run `pip install --force-reinstall fastmcp`. See the [FAQ](https://gofastmcp.com/more/faq) for why this happens (`uv` is unaffected).
+
 ## 📚 Documentation
 
 FastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns.
diff --git a/docs/docs.json b/docs/docs.json
index d4a131679..0fe46abe3 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -377,7 +377,8 @@
                       "updates",
                       "changelog"
                     ]
-                  }
+                  },
+                  "more/faq"
                 ]
               }
             ],
diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx
index 20443337b..5b4c4969a 100644
--- a/docs/getting-started/installation.mdx
+++ b/docs/getting-started/installation.mdx
@@ -62,6 +62,18 @@ Alternatively, wait for the stable v5 release. See [this issue](https://github.c
 </Info>
 ## Upgrading
 
+### From FastMCP 3.2 or earlier
+
+FastMCP 3.3 split the project into a metadata-only `fastmcp` distribution and a `fastmcp-slim` distribution that ships the importable code. When you upgrade directly from FastMCP 3.2 or earlier with `pip`, pip can write the new files and then delete them again while uninstalling the old `fastmcp` distribution, leaving `import fastmcp` broken even though the command reports success. `uv` upgrades in an order that avoids this.
+
+If `from fastmcp import FastMCP` fails after a `pip` upgrade, reinstall in a single step:
+
+```bash
+pip install --force-reinstall fastmcp
+```
+
+See the [FAQ](/more/faq) for the clean-reinstall fallback and an explanation of why this happens.
+
 ### From FastMCP 2.0
 
 See the [Upgrade Guide](/getting-started/upgrading/from-fastmcp-2) for a complete list of breaking changes and migration steps.
diff --git a/docs/more/faq.mdx b/docs/more/faq.mdx
new file mode 100644
index 000000000..63abc4f84
--- /dev/null
+++ b/docs/more/faq.mdx
@@ -0,0 +1,40 @@
+---
+title: FAQ
+description: Answers to common questions about installing and using FastMCP
+icon: circle-question
+---
+
+## `import fastmcp` stopped working after I upgraded with pip
+
+This affects one specific case: upgrading to FastMCP 3.3 or later from FastMCP 3.2 or earlier with `pip`. Fresh installs and `uv` upgrades are unaffected, so you can skip this section unless you did exactly that.
+
+If `import fastmcp` raises `ModuleNotFoundError` or `from fastmcp import FastMCP` raises `ImportError` immediately after the upgrade, your install is in a half-removed state. Reinstall in a single step:
+
+```bash
+pip install --force-reinstall fastmcp
+```
+
+If that doesn't resolve it, remove both distributions and reinstall from a clean state:
+
+```bash
+pip uninstall -y fastmcp fastmcp-slim
+pip install fastmcp
+```
+
+This happens because FastMCP 3.3 moved the importable code from the `fastmcp` distribution into `fastmcp-slim`. During a single-command `pip` upgrade, pip can install the new files and then delete them again while uninstalling the old `fastmcp` distribution, whose file manifest still lists those paths. The install reports success, but the code on disk is gone. `uv` uninstalls before it installs, so it is unaffected.
+
+## What's the difference between `fastmcp` and `fastmcp-slim`?
+
+`fastmcp` is the full distribution. Installing it gives you the complete framework — server, client, CLI, and the common integrations — and is the right choice for most users:
+
+```bash
+pip install fastmcp
+```
+
+`fastmcp-slim` ships the same importable `fastmcp` package with a minimal set of required dependencies. You opt into the pieces you need through extras, which keeps environments lean when you only use part of the framework:
+
+```bash
+pip install "fastmcp-slim[client]"
+```
+
+Both distributions expose the same `import fastmcp`, so application code is identical regardless of which one you install.