Deploy GPT Researcher v3.6.1: Install Guide

Most “autonomous research agent” write-ups sell the dream and skip the deploy tax. GPT Researcher is useful because it is boring infrastructure: planner + parallel executors that scrape, cite, and publish – not another chat wrapper. If v3.6.1 never comes up clean, the architecture talk is noise.

Deployment guide for open-source autonomous research agentGPT Researcher. GitHub tag v3.6.1 (24 Aug 2026). PyPI gpt-researcher 0.16.0 (18 Jul 2026). Keys in, process up, one verified run. Start here: official Getting Started.

System requirements (what actually matters)

The Linux deployment notes describe a small droplet-class box for light use. Community write-ups push the floor up once Deep Research or heavy browser scrapers enter the picture.

You will spend external API quota (OpenAI-class LLM + Tavily or another retriever). Docs ballpark a normal web report at ~3 minutes / ~$0.1 and Deep Research at ~5 minutes / ~$0.4 with high-reasoning models (as of the Deep Research docs). Ballpark only; your bill will wander.

Official download / source

• GitHub (source + Docker build context): https://github.com/assafelovic/gpt-researcher – checkout v3.6.1 when you need a known baseline.
• PyPI embed: pip install gpt-researcher==0.16.0
• Product / docs: gptr.dev, docs.gptr.dev
• Compose image name: gptresearcher/gpt-researcher – prefer docker compose build from the repo over a floating Hub latest

Skip random mirrors. Turns out GitHub tags (v3.x) and PyPI (0.x) are different numbering schemes – state both when you file bugs.

Install GPT Researcher (recommended: clone + venv)

Matches the official Getting Started path. FastAPI UI on port 8000.

# 1) Clone and enter
git clone https://github.com/assafelovic/gpt-researcher.git
cd gpt-researcher
git checkout v3.6.1 # optional, good baseline

# 2) Python 3.12+ venv (0.16.0 metadata: Requires-Python >=3.12)
python3.12 -m venv .venv
source .venv/bin/activate # Windows: .venvScriptsactivate

# 3) Dependencies
python -m pip install --upgrade pip
pip install -r requirements.txt

# 4) Env file
cp .env.example .env
# edit .env - next section

# 5) Run API + static UI
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Open http://localhost:8000. Want the fuller Next.js UI? Compose (below) and use port 3000.

Alternative A – pip package only (embed)

pip install gpt-researcher==0.16.0
export OPENAI_API_KEY=...
export TAVILY_API_KEY=...

Call GPTResearcher from async Python. No UI unless you wire one.

Alternative B – Docker Compose (UI + API)

cp .env.example .env # fill keys
docker compose up --build
# backend http://localhost:8000 | Next UI http://localhost:3000

Compose mounts ./my-docs, ./outputs, and ./logs into the backend. Local-document runs fail quietly when those paths are empty or unmounted – set DOC_PATH and bind-mount on purpose.

First-time configuration (minimum viable .env)

Minimum for a web research run, from .env.example and Getting Started:

OPENAI_API_KEY=sk-...
TAVILY_API_KEY=tvly-...
DOC_PATH=./my-docs
# optional:
# OPENAI_BASE_URL=https://api.openai.com/v1
# RETRIEVER=tavily
# LANGCHAIN_TRACING_V2=true
# LANGCHAIN_API_KEY=...

Pro tip: Prove Tavily + the default OpenAI-compatible chat path first. Half the install tickets start when people jump straight to exotic retriever/scraper combos – especially SCRAPER=tavily_extract on a prebuilt image.

You can point it at Ollama, Azure, Anthropic, and friends via env. Happy path is still OpenAI-class + Tavily. README lineage is explicit: planner/executor patterns inspired by Plan-and-Solve (arXiv:2305.04091) plus RAG-style aggregation – not one mega-prompt.

Verify the install works

Three cheap checks.

1. Process up:curl -s -o /dev/null -w "%{http_code}n" http://127.0.0.1:8000/ – want 200, not 404.
2. Import path:python -c "import gpt_researcher; print(gpt_researcher.__file__)" inside the venv (or after pip).
3. One real run: a narrow query you already know, then confirm something landed under outputs/ (clone UI/CLI) or that your embed script returned text + non-empty sources.

# pip-only async smoke (save as smoke.py)
import asyncio
from gpt_researcher import GPTResearcher

async def main():
 r = GPTResearcher(
 query="What is retrieval-augmented generation in one page?",
 report_type="research_report",
 )
 await r.conduct_research()
 report = await r.write_report()
 print(report[:500], "...", sep="n")
 print("costs:", r.get_costs())

asyncio.run(main())

Costs print and sources > 0? Install is real. “Scraped 0 pages” is almost never packaging – it is keys, retriever, or scraper.

Weird pause for a second: a green process check can still hide a hollow research loop. Empty scrapes feel like “AI is dumb” when the box simply never authenticated to the search API.

Common install errors and fixes

The ugly part. Pulled from GitHub issue themes (including #1625), not folklore.

• ModuleNotFoundError: No module named 'tavily' on Docker + Tavily extract – gptresearcher/gpt-researcher:latest reports where a runtime pip into a user site never reaches the uvicorn worker. Fix: build from the repo Dockerfile so tavily-python is baked in, or avoid that scraper until the image includes it. Pin a known-good tag; stop floating on latest.
• GET / → 404 Detail: Not Found after a fresh install – static/frontend routing drift after some cutovers (#1510-class). Start uvicorn main:app from repo root. Or docker compose up --build and use the Next UI on :3000. Bisect against the last tag that still served assets.
• Hang mid-run, UI “In progress”, CLI silent – confirmed intermittent hangs with custom retriever/LLM stacks (#1764-class). Enforce timeouts on LLM and search, restart the API process, re-test the provider alone before blaming the agent loop.
• 403 / model_not_found on a pinned GPT snapshot – the API key lacks that model. Point FAST_LLM / SMART_LLM (and embeddings) at models your account actually serves. ChatGPT Plus ≠ API model access.
• Local docs never show up – DOC_PATH is unreadable to the process, or Docker never mounted the host folder. Mount explicitly.

Upgrade and uninstall

Clone:git fetch --tags && git checkout v3.6.1 && source .venv/bin/activate && pip install -r requirements.txt. Re-diff .env against .env.example.

Pip:pip install -U gpt-researcher==0.16.0 (drop the pin only if you accept whatever PyPI serves next).

Docker:docker compose build --no-cache && docker compose up -d. Do not trust Hub latest alone when compose can build from source.

# cleanup
deactivate
rm -rf gpt-researcher # keep outputs/ first if you care
pip uninstall gpt-researcher -y
docker compose down --rmi local -v
rm -rf outputs logs my-docs

FAQ

Which install should I pick – pip, clone, or Docker?

Embed in code → pip 0.16.0. Built-in UI fast → clone + uvicorn or compose. Isolated host → compose build from the repo, not a blind Hub pull.

Why is my bill higher than “~$0.1”?

That number is the documented average for a standard pass. Deep Research, fatter corpora, and multi-agent flows multiply tool calls. Read get_costs() after one run and cut breadth/concurrency before you blame “random” pricing.

Python 3.11 still OK?

Some README/docs lines still say 3.11+. That collides with package reality: PyPI 0.16.0 (18 Jul 2026) declares Requires-Python >=3.12, and the project image tracks 3.12-slim. If pip refuses the install, the interpreter is wrong – not your lockfile. Stay on 3.12+ for current package installs. Older GitHub tags? Read that tag’s classifiers before forcing an old runtime onto a new wheel.

Next: paste the clone block, real keys in .env, uvicorn up, one narrow research_report you can fact-check by eye – empty scrapes show up in minutes.