From 853b15fb3db5b9934d1fb7f739562c755c05abe2 Mon Sep 17 00:00:00 2001 From: iris-clawd Date: Thu, 7 May 2026 18:37:26 +0000 Subject: [PATCH] docs: add upgrading-crewai guide and installation note Co-Authored-By: Claude Opus 4.7 --- docs/docs.json | 33 +++++--- docs/en/guides/migration/upgrading-crewai.mdx | 81 +++++++++++++++++++ docs/en/installation.mdx | 3 + 3 files changed, 106 insertions(+), 11 deletions(-) create mode 100644 docs/en/guides/migration/upgrading-crewai.mdx diff --git a/docs/docs.json b/docs/docs.json index e2fe48ff0..c4277b3f7 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -144,7 +144,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] @@ -620,7 +621,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] @@ -1096,7 +1098,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] @@ -1572,7 +1575,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] @@ -2048,7 +2052,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] @@ -2524,7 +2529,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] @@ -2998,7 +3004,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] @@ -3472,7 +3479,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] @@ -3947,7 +3955,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] @@ -4423,7 +4432,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] @@ -4897,7 +4907,8 @@ "group": "Migration", "icon": "shuffle", "pages": [ - "en/guides/migration/migrating-from-langgraph" + "en/guides/migration/migrating-from-langgraph", + "en/guides/migration/upgrading-crewai" ] } ] diff --git a/docs/en/guides/migration/upgrading-crewai.mdx b/docs/en/guides/migration/upgrading-crewai.mdx new file mode 100644 index 000000000..4f9c63f99 --- /dev/null +++ b/docs/en/guides/migration/upgrading-crewai.mdx @@ -0,0 +1,81 @@ +--- +title: "Upgrading CrewAI in Your Project" +description: "How to upgrade the crewai version inside your project's virtual environment — and why crewai install alone won't do it." +icon: "arrow-up-circle" +--- + +## The Two Things You Might Want to Upgrade + +CrewAI lives in two places on your machine, and they upgrade independently: + +| What | How it's installed | How to upgrade | +|---|---|---| +| The **global `crewai` CLI** | `uv tool install crewai` | `uv tool install crewai --upgrade` | +| The **project venv** (what your code runs) | `crewai install` / `uv sync` | `uv add "crewai[...]>=X.Y.Z"` then `crewai install` | + +These can — and often do — get out of sync. Running `crewai --version` tells you the CLI version. Running `uv pip show crewai` inside your project tells you the venv version. If they differ, that's normal; what matters for your running code is the venv version. + +## Why `crewai install` Doesn't Upgrade + +`crewai install` is a thin wrapper around `uv sync`. It installs exactly what the current `uv.lock` file says — it does **not** bump any version constraints. + +If your `pyproject.toml` says `crewai>=1.11.1` and the lock file resolved to `1.11.1`, running `crewai install` will keep you on `1.11.1` forever, even if `1.14.4` is available. + +To actually upgrade, you need to: +1. Update the version constraint in `pyproject.toml` +2. Re-solve the lock file +3. Sync the venv + +`uv add` does all three in one shot. + +## How to Upgrade Your Project + +```bash +# Bump the constraint and re-lock in one command +uv add "crewai[tools]>=1.14.4" + +# Sync the venv (crewai install calls uv sync under the hood) +crewai install + +# Verify +uv pip show crewai +# → Version: 1.14.4 +``` + +Replace `[tools]` with whatever extras your project uses (e.g. `[tools,anthropic]`). Check your `pyproject.toml` `dependencies` list if you're unsure. + + + `uv add` updates both `pyproject.toml` **and** `uv.lock` atomically. If you edit `pyproject.toml` manually, you still need to run `uv lock --upgrade-package crewai` to re-solve the lock file before `crewai install` will pick up the new version. + + +## Verify Both Are in Sync + +```bash +# Global CLI version +crewai --version + +# Project venv version +uv pip show crewai | grep Version +``` + +They don't need to match — but your project venv version is what matters for runtime behavior. + +## Common Gotchas + +**The constraint is a floor, not a pin.** `crewai>=1.11.1` means "any version at or above 1.11.1." uv will pick the highest compatible version when re-locking — but only if you explicitly re-lock with `uv add` or `uv lock --upgrade-package crewai`. + +**You have a `uv.lock` file.** If you commit `uv.lock`, your teammates get the exact same versions. After bumping with `uv add`, commit the updated `uv.lock` too. + +**Extras must be consistent.** If you run `uv add "crewai>=1.14.4"` without extras, uv may drop `[tools]` from the resolved set. Always include the extras you need: `uv add "crewai[tools]>=1.14.4"`. + +**Dependency conflicts.** If uv can't resolve the new version against your other dependencies, it will tell you which package conflicts. Pin or upgrade the conflicting package explicitly. + +## Upgrading the Global CLI + +The global CLI is separate from your project. Upgrade it with: + +```bash +uv tool install crewai --upgrade +``` + +This does **not** touch your project's venv. diff --git a/docs/en/installation.mdx b/docs/en/installation.mdx index 50f43ff9d..538ad56d7 100644 --- a/docs/en/installation.mdx +++ b/docs/en/installation.mdx @@ -106,6 +106,9 @@ If you haven't installed `uv` yet, follow **step 1** to quickly get it set up on ```shell uv tool install crewai --upgrade ``` + + This upgrades the **global `crewai` CLI tool** only. To upgrade the `crewai` version inside your project's virtual environment, see [Upgrading CrewAI in a project](/en/guides/migration/upgrading-crewai). + Installation successful! You're ready to create your first crew! 🎉