Skip to content
Get packs

Guide · Open source

How to use MetaGPT: install, configure and run your first project

Updated · written with AI from the project's own documentation and checked against our catalogue data

MetaGPT is an open-source Python framework that gives LLM-based agents software-company roles such as product manager, architect, project manager and engineer. You give it a one-line requirement and the agents produce artifacts such as user stories, requirements, data structures, APIs and code. This guide covers installation, configuration, running your first project from the command line or as a Python library, and where the tool's limits are.

MetaGPTFoundationAgents/MetaGPT · ★ 71.1k · MIT

Quick start

  1. 1Check your Python version. Confirm Python is 3.9 or later but below 3.12, and install Node.js and pnpm.
  2. 2Install the package. Run pip install --upgrade metagpt.
  3. 3Create the config file. Run metagpt --init-config to generate ~/.metagpt/config2.yaml.
  4. 4Add your LLM settings. Edit config2.yaml with your api_type, model, base_url and api_key.
  5. 5Run a requirement. Run metagpt "Create a 2048 game" and check the output in ./workspace.

What you need before installing MetaGPT

MetaGPT requires Python 3.9 or later but less than 3.12. You can check your version with the python command. Node.js and pnpm must also be installed before actual use.

You also need an LLM API key or a compatible local model endpoint. Configuration is required before MetaGPT can run.

  • Python 3.9 or later, but less than 3.12
  • Node.js and pnpm
  • An LLM API key or a compatible local model endpoint
python --version

Install MetaGPT from PyPI

The simplest route is to install the package from PyPI with pip. The README also lists two alternatives: installing directly from the GitHub repository, or cloning the repo and installing it in editable mode. For detailed guidance, the project points to its CLI and Docker installation docs.

The README suggests conda if you want an isolated environment, for example with Python 3.9.

pip install --upgrade metagpt # or pip install --upgrade git+https://github.com/geekan/MetaGPT.git # or git clone https://github.com/geekan/MetaGPT && cd MetaGPT && pip install --upgrade -e . # optional isolated environment conda create -n metagpt python=3.9 && conda activate metagpt

Create and edit the configuration file

MetaGPT reads its settings from ~/.metagpt/config2.yaml. You can generate that file with the init command, or create it manually. Then open it and set your LLM details.

The README example uses the openai api_type with a model, base_url and api_key. The file also notes that other options such as azure, ollama or groq are possible; check the LLMType options in the project docs for the full list.

  • api_type: the provider type, for example openai
  • model: the model name, for example gpt-4-turbo
  • base_url: the API endpoint, for example https://api.openai.com/v1 or a forwarding URL
  • api_key: your own key, replacing YOUR_API_KEY
metagpt --init-config # ~/.metagpt/config2.yaml llm: api_type: "openai" model: "gpt-4-turbo" base_url: "https://api.openai.com/v1" api_key: "YOUR_API_KEY"

Run your first project from the command line

After installation and configuration, the README shows the CLI usage pattern: pass a one-line requirement in quotes. The example requirement is a 2048 game. According to the README, this creates a repo in ./workspace.

Because the agents generate code, review what appears in the workspace before relying on it. The README does not guarantee production-ready output.

  • Output is written to ./workspace
  • The README's example requirement is "Create a 2048 game"
metagpt "Create a 2048 game" # this will create a repo in ./workspace

Use MetaGPT as a Python library

You can call the framework from Python instead of the CLI. The README shows generate_repo, which takes a requirement and returns a ProjectRepo object. You can also pass a path to load an existing ProjectRepo.

The README also documents Data Interpreter, a separate entry point in the same project, for writing code for tasks such as data analysis. The example runs it asynchronously against the sklearn Iris dataset.

  • generate_repo(requirement) returns a ProjectRepo; print it to see the repo structure
  • ProjectRepo(path) opens an existing project
  • DataInterpreter().run(task) is the Data Interpreter entry point
from metagpt.software_company import generate_repo from metagpt.utils.project_repo import ProjectRepo repo: ProjectRepo = generate_repo("Create a 2048 game") # or ProjectRepo("<path>") print(repo)

Learn more and get help

The project's online documentation covers usage, the product scope, and how to build your own agents, including Agent 101 and MultiAgent 101 guides. The README also links use cases such as Data Interpreter, Debate, Researcher and Receipt Assistant, plus an FAQ page.

For questions, the README lists a Discord channel, a Contributor form, and GitHub Issues for technical inquiries. It states that the maintainers will respond within 2-3 business days.

  • Official docs: docs.deepwisdom.ai/main/en/
  • Agent 101 and MultiAgent 101 tutorials
  • GitHub Issues for technical questions

What people use it for

  • Generating a small software prototype from a one-line requirement
  • Experimenting with role-based multi-agent collaboration using standard operating procedures
  • Running the Data Interpreter on a data analysis task, such as the sklearn Iris dataset with a plot
  • Studying how agent teams are built, using the project's Agent 101 and MultiAgent 101 guides

Frequently asked questions

Is MetaGPT free to use?

MetaGPT is released under the MIT licence, according to the project listing. The README does not cover the cost of the LLM API you connect, which you supply yourself through your api_key or a local model endpoint.

What Python version does MetaGPT need?

The README says Python 3.9 or later but less than 3.12. Node.js and pnpm must also be installed before actual use.

How do I install MetaGPT?

Run pip install --upgrade metagpt. The README also lists installing from the GitHub repository or cloning and installing in editable mode.

Why does MetaGPT ask for an API key?

MetaGPT needs an LLM to power its agents. You can supply an API key for a provider such as OpenAI in config2.yaml, or point base_url to a compatible local model endpoint.

Can MetaGPT generate production-ready code?

The README does not make guarantees about production-ready code. Review the generated output before using it, and treat the results as a starting point for prototypes.

How does MetaGPT compare to AutoGen, CrewAI, ChatDev or OpenHands?

These are listed as comparable projects in the directory entry. MetaGPT's distinguishing idea, per its README, is Code = SOP(Team), which applies standard operating procedures to teams of LLM roles. For a direct feature comparison, check each project's own documentation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

MetaGPT suits developers, researchers and students who want to experiment with role-based multi-agent LLM workflows and generate small prototypes. It is a poor fit if you need reliable production code without review, if you don't have an LLM API key or local model, or if you want a no-code, point-and-click tool, since the README centers on CLI and Python use.

Install options & downloads