ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-23 05:54:19 +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

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.