QWE AI Academy CrewAI install can “succeed” and crewai run still acts like last month’s build. The framework ships as two installs: a global CLI and a per-project virtualenv. This guide pins CrewAI 1.15.17 the way the maintainers document it – uv-first, verified, upgrade-safe.
CrewAI is an open-source Python framework for multi-agent crews and event-driven Flows (independent of LangChain). Package page: crewai on PyPI (listed there as 1.15.17, Aug 20, 2026 upload per project metadata). Release tags live on crewAIInc/crewAI releases.
System requirements before you touch uv
Local OSS is a normal Python CLI stack – not the enterprise Helm path (self-hosted charts quote roughly 14Gi memory / 4 CPU minimum for cluster deploy; you do not need that on a laptop).
| Item | Minimum | Notes |
|---|---|---|
| OS | macOS, Linux, or Windows | Windows often needs C++ build tools when wheels compile from source |
| Python | >=3.10 and <3.14 | Per official install docs (as of the v1.15.16 doc tree). 3.11-3.12 see fewer edge reports than 3.13 |
| Package manager | uv (official path) or pip | CLI tooling and project locks assume uv |
| Network / keys | HTTPS to PyPI + your LLM provider | Provider key in .env (for example OPENAI_API_KEY) |
Check Python first: python3 --version (or py -3 --version on Windows). Outside 3.10-3.13 and the install story gets ugly fast.
Official download sources
Skip random forks. Use:
- CLI / library: PyPI
crewai– 1.15.17 as listed on the project page above - Install + upgrade docs: docs.crewai.com (linked where commands matter below)
- Source / tags: github.com/crewAIInc/crewAI
Pip still works (pip install crewai or pip install 'crewai[tools]'). Supported path for the global CLI is uv tool install, then project deps via crewai install.
Install CrewAI 1.15.17 step by step
uv first. Global crewai tool second. That pair drives create, install, and run.
# 1) Install uv
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# or: wget -qO- https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 2) Global CrewAI CLI
uv tool install crewai
# If PATH warns that the tool isn't found:
uv tool update-shell
# then open a new terminal
# 3) Confirm the tool is registered
uv tool list
crewai --versionYou want uv tool list to show crewai and crewai --version on the 1.15.x line (target 1.15.17 if you are matching the PyPI upload called out above). Pin when you must: uv tool install crewai==1.15.17.
Refuse uv for the library only? pip install crewai==1.15.17 inside a venv. You still want the CLI available for scaffolding.
First-time configuration: minimum viable crew project
Scaffold is JSON-first now. Older tutorials still paste YAML trees – that mismatch burns first deploys more than missing API keys.
crewai create crew deploy_smoke_test
cd deploy_smoke_test
# Optional: old layout with crew.py + config/agents.yaml + tasks.yaml
# crewai create crew deploy_smoke_test --classic
# Put secrets only in .env (never commit)
# OPENAI_API_KEY=sk-...
# or your provider's key + MODEL=...
crewai install
crewai runEdit crew.jsonc and agents/*.jsonc for roles/goals; placeholders like {topic} resolve from inputs or prompts on run. Extra packages: uv add package-name inside the project.
Pro tip: After
crewai install, runuv pip show crewaiin the project. That version is what executes. The global CLI string can lag or lead on purpose.
If you learned crews from a 2024 YAML course, the new tree feels wrong for a day. Same agent ideas – different files on disk. That is a product default change, not a broken scaffold.
Verify the install actually works
Three checks:
uv tool list– global CLI presentcrewai --version– CLI version string- Inside the project:
uv pip show crewai, then a shortcrewai runwith a valid API key
Agents start (or fail only on bad credentials)? Deploy path is fine. Silent hang or import error? Project venv – not the global tool.
Common install errors and fixes
These dominate GitHub issues and the CrewAI forum.
- Windows:
Failed building wheel for chroma-hnswlib/fatal error C1083: Cannot open include file: 'float.h'(orcrtdbg.h) / MSVC 14.0 required – Install Visual Studio Build Tools with Desktop development with C++; add the Windows SDK if headers still missing. Official install docs call this out for chroma-hnswlib 0.7.6. ModuleNotFoundError: No module named 'tiktoken'– extras:uv pip install 'crewai[embeddings]'or'crewai[tools]'(also noted on the PyPI page).crewainot found after install –uv tool update-shell, new terminal,uv tool list. Windows PATH drift after the first uv tool install is common.- Odd “can’t resolve package cut yesterday” – internal packages set
exclude-newer = "3 days"as a supply-chain brake (install docs). Pin the dep directly, or wait out the window.
Upgrade path and clean uninstall
crewai install alone never raises version caps in pyproject.toml. The official upgrading guide splits CLI vs project on purpose.
# Upgrade global CLI only
uv tool install crewai --upgrade
# or pin: uv tool install crewai==1.15.17
# Upgrade the project that actually runs your agents
uv add "crewai[tools]>=1.15.17"
crewai install
uv pip show crewai # confirm Version: 1.15.17
# Uninstall global CLI
uv tool remove crewai
# Project cleanup: delete the project folder and its .venv / uv.lock
# (or drop the dependency from pyproject.toml and uv lock / uv sync)CLI version check: crewai --version. Project package: uv pip show crewai. Community uninstall path for the tool is uv tool remove crewai.
Most “CrewAI broke after update” threads are not a broken framework. Two version numbers. People treated them as one variable.
FAQ
Do I need Docker to run CrewAI agents locally?
No. Python + uv + API keys. Docker/Kubernetes shows up for enterprise self-hosted layouts, not the OSS CLI smoke test.
pip install crewai vs uv tool install crewai – which should I use?
Prefer uv tool install crewai so the supported CLI stays on PATH, then let crewai install own the project lockfile. Example: you already have an app venv managed by pip – pip install crewai==1.15.17 is fine for importing the library there, but you will recreate CLI gaps and lock drift uv was meant to avoid. Poetry shops that hit resolver fights still get steered toward uv for new crews in the current docs.
Why does my new project look nothing like the YAML tutorials?
Default scaffold is JSON-first (agents/*.jsonc, crew.jsonc) per current install docs. Older courses and long-form PyPI readme material still show config/agents.yaml plus crew.py. Pass --classic at create time if a course or script expects that layout.
Open a terminal, run the uv + uv tool install crewai block, scaffold deploy_smoke_test, set one real API key, and execute crewai run before you draw multi-agent architecture diagrams.