CrewAI is a powerful framework for building multi-agent AI systems where autonomous agents collaborate to complete complex tasks. While the framework is well-documented for Linux and macOS, Windows users often encounter unique challenges during setup. This tutorial documents the real-world troubleshooting journey of getting CrewAI running on Windows, covering every error and its solution.
What You’ll Learn: How to resolve common Windows installation errors, configure API keys correctly, and successfully run your first CrewAI project.
Prerequisites
- Python 3.10+ installed
- Windows 10/11
- Visual Studio Build Tools 2019 or later
- An API key from OpenAI or Anthropic
Issue 1: Command Not Recognized
The Error
crewai : The term ‘crewai’ is not recognized as the name of a cmdlet, function, script file, or operable program.
Why It Happens
PowerShell cannot find the crewai command because either CrewAI isn’t installed, or you’re not in the virtual environment where it’s installed.
The Solution
If you already have a virtual environment, activate it:
.\.venv\Scripts\Activate
If you don’t have one, create it and install CrewAI:
python -m venv .venv.\.venv\Scripts\Activatepip install crewai crewai-tools
Issue 2: C++ Build Failure (chroma-hnswlib)
The Error
Failed to build chroma-hnswlib==0.7.6fatal error C1083: Cannot open include file: ‘crtdbg.h’: No such file or directory
Why It Happens
CrewAI depends on ChromaDB for its vector database, which requires compiling C++ code. Your Visual Studio Build Tools installation is missing the Windows SDK component needed for this compilation.
The Solution
- Open Visual Studio Installer (search for it in Start menu)
- Find your Build Tools installation and click Modify
- Under “Individual components”, check: Windows 10 SDK (or Windows 11 SDK) and C++ CMake tools for Windows
- Click Modify and wait for installation to complete
- Restart your terminal and run crewai run again
Issue 3: ONNX Runtime DLL Load Failure
The Error
ImportError: DLL load failed while importing onnxruntime_pybind11_state: A dynamic link library (DLL) initialization routine failed.ValueError: The onnxruntime python package is not installed.
Why It Happens
ChromaDB uses ONNX Runtime for its default embedding function. The DLL load failure typically indicates a missing Visual C++ Redistributable on your system.
The Solution
Download and install the Visual C++ Redistributable from Microsoft:
After installing, restart your terminal and try again. If the issue persists, you can reinstall onnxruntime in the project’s virtual environment:
.\.venv\Scripts\Activatepip uninstall onnxruntime -ypip install onnxruntimedeactivatecrewai run
Issue 4: Missing API Key
The Error
litellm.AuthenticationError: Missing Anthropic API Key – A call is being made to anthropic but no key is set either in the environment variables or via params. Please set `ANTHROPIC_API_KEY` in your environment vars
Why It Happens
CrewAI uses LiteLLM to connect to various LLM providers. When your crew runs, it needs an API key to make calls to the configured model. If the environment variable isn’t set or is named incorrectly, you’ll see this error.
The Solution
Option A: Set temporarily in PowerShell
$env:ANTHROPIC_API_KEY = “your-api-key-here”# OR for OpenAI:$env:OPENAI_API_KEY = “your-api-key-here”
Option B: Create a .env file (Recommended)
Create a file named .env in your project root with:
ANTHROPIC_API_KEY=your-anthropic-key-here# OROPENAI_API_KEY=your-openai-key-here
Pro Tip: Double-check your environment variable names! A common mistake is typos like ANTHROPIC_KEY instead of ANTHROPIC_API_KEY. The exact spelling matters.
Issue 5: Insufficient API Credits
The Error
litellm.BadRequestError: AnthropicException – Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits.
Why It Happens
Your API account has run out of credits. This is straightforward – you need to either add credits or switch to a different provider.
The Solution
Option A: Add credits to your Anthropic account at console.anthropic.com
Option B: Switch to OpenAI or another provider by updating your agents.yaml file:
# In src/your_project/config/agents.yamldebater: role: “A compelling debater” llm: gpt-4o-mini # or gpt-4o for better quality
Quick Reference: Error Summary
| Error | Cause | Solution |
| Command not recognized | Not in virtual environment | Activate .venv |
| chroma-hnswlib build fail | Missing Windows SDK | Install via VS Installer |
| DLL load failed | Missing VC++ Redistributable | Install from Microsoft |
| Missing API Key | Env variable not set/typo | Check .env file spelling |
| Credit balance too low | No API credits | Add credits or switch provider |
Conclusion
Setting up CrewAI on Windows requires a few extra steps compared to Linux or macOS, primarily around C++ build dependencies. The key takeaways are:
- Install Windows SDK through Visual Studio Build Tools for C++ compilation
- Install Visual C++ Redistributable for ONNX Runtime DLL support
- Use exact environment variable names (ANTHROPIC_API_KEY, OPENAI_API_KEY)
- Create a .env file for persistent API key configuration
Once you’ve resolved these initial setup challenges, CrewAI provides a powerful platform for building sophisticated multi-agent AI applications. Happy building!