Install MetaGPT v0.8.2: Deploy an AI Software Engineer

Here’s a fact most tutorials skip: the last tagged GitHub release of MetaGPT is v0.8.1, pushed in late March 2024 – yet the team launched MGX (MetaGPT X), their commercial AI agent product, on February 19, 2025. So when you deploy the open-source software engineer AI, you’re deploying a framework whose OSS cadence has slowed while its commercial sibling sprints. That changes how you should think about pinning versions.

This guide deploys MetaGPT v0.8.x – the one on PyPI as metagpt-0.8.2 – using the recommended pip path, then patches the four things that actually break on a fresh box.

What you’re actually installing

MetaGPT is a multi-agent framework where each agent plays a role from a software org. Internally, MetaGPT includes product managers, architects, project managers, and engineers. It provides the entire process of a software company along with carefully orchestrated SOPs. Code = SOP(Team) is the core philosophy. SOP is materialized and applied to teams composed of LLMs. The underlying research was accepted as an oral presentation (top 1.2%) at ICLR 2024, ranking #1 in the LLM-based Agent category – paper at arXiv:2308.00352.

Translation: you give it one sentence, four LLM agents argue about it, and you get a repo.

System requirements (and the Python 3.12 trap)

The single most common failed install comes from Python version. Ensure that Python 3.9 or later, but less than 3.12, is installed on your system. Not “3.9+” like a lot of mirrored READMEs claim. The upper bound matters – Python 3.12 will let pip install metagpt complete and then explode on first import.

For the LLM: if you’re using OpenAI, there’s a billing gotcha. OpenAI requires a minimum $1 spend to access GPT-4, and running a small workload with gpt-3.5-turbo (after free credits are used) generally unlocks GPT-4 access. A fresh API key set to gpt-4-turbo will return model not found until you’ve burned a dollar. Not a MetaGPT bug.

Install via pip (the recommended path)

Use conda for isolation – mixing this into your system Python is asking for dependency hell.

# 1. Create an isolated env
conda create -n metagpt python=3.11 -y
conda activate metagpt

# 2. Install from PyPI
pip install --upgrade metagpt

# 3. Verify the binary registered
metagpt --help

If you want the bleeding edge instead of PyPI, the canonical source URL is still git+https://github.com/geekan/MetaGPT.git per the official README, even though the repo’s canonical owner is now FoundationAgents. Both URLs resolve to the same code – GitHub redirects – but old CI pipelines pinning a SHA from the old org may behave oddly. Worth a note in your infra docs.

Docker alternative (one-shot, no env mess)

If you’d rather not touch your local Python at all, the official image is metagpt/metagpt:latest, pulled with docker pull metagpt/metagpt:latest, then mounted via /opt/metagpt/config and /opt/metagpt/workspace. Container needs --privileged because the agents shell out to run generated code.

First-time config: where most installs die

v0.8 changed the config format. The old config.yaml and key.yaml were removed and replaced with a minimal config2.yaml. Old blog posts (and a surprising amount of LLM-generated advice) still reference the dead format. Ignore them.

Generate the file:

metagpt --init-config
# Creates ~/.metagpt/config2.yaml

Then edit it. The minimum viable config is six lines:

llm:
 api_type: "openai"
 model: "gpt-4-turbo"
 base_url: "https://api.openai.com/v1"
 api_key: "sk-..."

The api_type field accepts openai, azure, ollama, groq, and others – check LLMType for the full list. If you point it at a local Ollama, expect markedly slower runs and lower code quality than GPT-4 – the framework was tuned against frontier models.

Pro tip: Set --investment 3.0 on your first run. That caps OpenAI spend at $3 for the project. A misconfigured PRD loop can otherwise chew through $20 before you notice.

Verify it works without burning $5 on the 2048 demo

Every tutorial tells you to run the snake game or 2048 example. Skip them. Verify the install with the cheapest possible call first:

# Check version and CLI is healthy
metagpt --help

# Tiny end-to-end test - one file, minimal tokens
metagpt "Write a Python function that reverses a string" --max-auto-summarize-code 0

If you see the four agents (ProductManager → Architect → ProjectManager → Engineer) print their stages and a workspace/ folder appears with a generated repo inside, you’re done. The CLI exposes flags like –project-name, –inc for incremental mode against an existing repo, –project-path to point at the old version, and –recover-path to resume from serialized storage – useful once you scale up.

Common errors and the fixes that actually work

• ERROR: Could not find a version that satisfies the requirement metagpt – you’re on Python 3.12+. Downgrade to 3.11.
• The model gpt-4 does not exist – OpenAI billing issue, not MetaGPT. Spend the $1 minimum or switch model to gpt-3.5-turbo temporarily.
• Mermaid diagrams never render – pyppeteer is no longer maintained; the docs recommend playwright-python as a replacement, which requires installing its own browser. Run pip install playwright && playwright install --with-deps chromium, then set the engine to playwright in config2.yaml. Alternatively, use ink for online rendering – no local browser, but only PNG/SVG.
• Hangs forever on free OpenAI credits – if free credits remain, the FAQ recommends setting RPM to 3 or lower, or upgrading to a paid plan if credits are depleted.
• requirements.txt conflicts during a source install – delete the lockfile and retry, or manually run pip install -r requirements.txt.

Upgrade and uninstall

Upgrade is a one-liner inside your conda env:

pip install --upgrade metagpt

If you’re moving up from a pre-0.8 install, your old config.yaml and key.yaml are dead weight. Re-run metagpt --init-config and migrate values into config2.yaml by hand – there’s no auto-migration script. The schema’s different enough that copy-paste won’t work.

Uninstall is equally boring:

pip uninstall metagpt
rm -rf ~/.metagpt
conda deactivate && conda env remove -n metagpt

That removes the package, the config, and the entire env. Workspace folders (anywhere you ran metagpt "...") are independent – delete them separately if you don’t want the generated repos.

FAQ

Is MetaGPT still maintained?

Unclear. The last GitHub release tag is v0.8.1 from March 2024, while the team shipped a commercial product (MGX) in February 2025. The repo still receives commits, but version cadence has slowed. Pin your dependency.

Can I run MetaGPT fully offline with a local model?

Technically yes – set api_type: "ollama" in config2.yaml and point it at a local server. In practice, smaller open models struggle with the multi-step PRD → architecture → code chain, and you’ll see incomplete or hallucinated outputs on anything beyond toy scripts. The framework was benchmarked against GPT-4-class models in the ICLR paper, and the quality drop on a 7B local model is steep.

What’s the difference between MetaGPT and the new MGX?

MetaGPT is the open-source Python framework you install yourself. MGX is the hosted product. Same team, different deployment model – use the OSS framework when you need control, the hosted one when you don’t.

Next: open ~/.metagpt/config2.yaml, plug in your key, and ship one real prompt – something you’d actually use, not the 2048 game. That’s where you’ll learn what this framework can and can’t do.