ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-20 12:34:17 +02:00
Code Issues Projects Releases Packages Wiki Activity

Move pip upgrade recovery into a Troubleshooting section (#4219)

Browse source
This commit is contained in:
Jeremiah Lowin 2026-05-22 21:13:19 -04:00 • committed by GitHub
commit 986af54afa
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 23 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -105,7 +105,7 @@ For full installation instructions, including verification and upgrading, see th
- [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).
> If `import fastmcp` fails right after a `pip` upgrade from FastMCP 3.2 or earlier, run `pip install --force-reinstall fastmcp`. See [Troubleshooting](https://gofastmcp.com/getting-started/installation#troubleshooting) for why this happens (`uv` is unaffected).
## 📚 Documentation

33
docs/getting-started/installation.mdx
View file

@ -62,18 +62,6 @@ 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.
@ -88,6 +76,27 @@ If you're using FastMCP 1.0 via the `mcp` package (meaning you import FastMCP as
If you built your server directly on the `mcp` package's `Server` class — with `list_tools()`/`call_tool()` handlers and hand-written JSON Schema — see the [migration guide](/getting-started/upgrading/from-low-level-sdk) for a full walkthrough.
## Troubleshooting
### `import fastmcp` fails after a pip upgrade
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 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
```
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 while uninstalling the old `fastmcp` distribution, whose file manifest still lists those paths. `uv` uninstalls before it installs, so it is unaffected.
## Versioning Policy
FastMCP follows semantic versioning with pragmatic adaptations for the rapidly evolving MCP ecosystem. Breaking changes may occur in minor versions (e.g., 2.3.x to 2.4.0) when necessary to stay current with the MCP Protocol.

17
docs/more/faq.mdx
View file

@ -6,22 +6,7 @@ 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.
This can happen when you upgrade to FastMCP 3.3 or later from FastMCP 3.2 or earlier with `pip`. The quick fix is `pip install --force-reinstall fastmcp`. See [Troubleshooting](/getting-started/installation#troubleshooting) for the clean-reinstall fallback and an explanation of why it happens.
## What's the difference between `fastmcp` and `fastmcp-slim`?