Document pip upgrade recovery for the fastmcp-slim package split (#4215)

docs/docs.json

@@ -377,7 +377,8 @@
                       "updates",
                       "changelog"
                     ]
-                  }
+                  },
+                  "more/faq"
                 ]
               }
             ],

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.

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.