π The fast, Pythonic way to build MCP servers and clients.
Document pip upgrade recovery for the fastmcp-slim package split (#4215)
Jeremiah Lowin7a82b57efb88
diff --git a/README.md b/README.mdindex 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).+## π DocumentationFastMCP'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.jsonindex 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.mdxindex 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.0See 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.mdxnew file mode 100644index 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.