Install gptme 0.33.0: CLI LLM Tool Deploy Guide

Most people treat a CLI LLM tool like a chat wrapper you pip-install and forget. Wrong move. gptme 0.33.0 is a full agent runtime – shell, files, browser, subagents – so a sloppy install leaves you with half the tools and mystery failures later. Deploy it clean once.

Path for the current stable release only: requirements, commands, minimum config, verification, the errors that actually show up, then upgrade and uninstall. No feature tour.

System requirements for gptme

From the project’s getting-started notes and packaging metadata:

Stable packages report 0.33.0 on PyPI and Homebrew as of the latest check for this guide. Browser work is a two-step problem later – Python extra ≠ browser binaries.

Official download sources

Use only these:

• One-line installer: https://gptme.ai/install.sh
• PyPI: pypi.org/project/gptme (0.33.0)
• GitHub: github.com/gptme/gptme
• Docs: gptme.org/docs/getting-started
• Homebrew: brew install gptme

Skip random mirrors. Dev tags on GitHub move fast; stick to 0.33.0 unless you intentionally want HEAD.

Install gptme 0.33.0 step by step

Pick one path. pipx or the curl installer is what most people use in practice.

Recommended: one-line installer

curl -sSf https://gptme.ai/install.sh | sh

Per the getting-started docs, it detects uv or pipx, installs gptme with browser support by default, and accepts flags like --extras, --no-extras, --dev, --yes.

pipx (isolated)

# if needed
pip install --user pipx
pipx ensurepath

pipx install gptme
# or with common extras
pipx install "gptme[browser,server]"
# everything the extra set allows
pipx install "gptme[all]"

uv tool

uv tool install gptme
# extras:
uv tool install "gptme[browser]"

Homebrew

brew install gptme

From git (latest master)

pipx install "git+https://github.com/gptme/gptme.git"
# editable clone:
git clone https://github.com/gptme/gptme.git && cd gptme
pipx install -e ".[server,browser]"

Pro tip:[browser] only pulls the Playwright library. Binaries are separate – see system-dependencies and the errors section below for playwright install chromium-headless-shell (pin to the Playwright version gptme shipped).

Docker self-host (server + web UI on :5700): clone the repo, copy .env.example → .env with at least one provider key, then docker compose up --build (server docs).

Half the “install guides” online stop at a green pip exit code. That’s the easy half. The boring half is secrets layout and proving the agent can actually see a browser binary.

First-time configuration

Run gptme once. Missing provider? It prompts and can write credentials. Put secrets in the local override – not the main file.

mkdir -p ~/.config/gptme

# preferences (safe to commit in dotfiles)
cat > ~/.config/gptme/config.toml <<'EOF'
[user]
name = "You"
about = "I write code and automate boring work."

[models]
default = "anthropic/claude-sonnet-4-5"

[env]
# MODEL can live here too; [models].default wins in the same file
EOF

# secrets only
cat > ~/.config/gptme/config.local.toml <<'EOF'
[env]
ANTHROPIC_API_KEY = "sk-ant-..."
# OPENAI_API_KEY = "sk-..."
# OPENROUTER_API_KEY = "sk-or-..."
EOF

Config paths come from the configuration docs: ~/.config/gptme/config.toml for prefs, config.local.toml for keys.

Subscription path (no separate API key purchase): gptme-auth openai-subscription or gptme-auth grok-subscription, or gptme-onboard. For Ollama:

ollama pull llama3.1:8b
export OPENAI_BASE_URL="http://127.0.0.1:11434/v1"
gptme -m local/llama3.1:8b "hello"

OPENAI_BASE_URL only applies to local/ models. Free OpenRouter: the id that works is doubled – details under install errors if a bare openrouter/free 404s on you.

Verify the install works

gptme --version
gptme-doctor
gptme providers list
gptme "reply with exactly: pong"

gptme-doctor (and in-session /doctor) is the real gate – providers, optional deps, Playwright browsers. Version string + one-shot reply means the CLI path is live. Optional: gptme-server, then http://localhost:5700 if you took the server extra.

Watching the doctor spit green after a fresh pipx install still feels better than it should.

Common install errors and fixes

1. ModuleNotFoundError: No module named ‘readline’ on native Windows – expected. Official stance: WSL2 or Docker, not raw Windows Python.
2. Browser tool not available / URL reads skipped – extra installed, binaries not. From the system-dependencies docs: install chromium-headless-shell (or firefox) for the Playwright version gptme pinned; pipx runpip gptme / matching playwright==... when the tool is isolated.
3. ValueError: Provider local did not have a summary model – local provider has no default summary model. Set summary in config or pass -m local/YOUR_MODEL so chat and summaries share the model.
4. Build failures on very new Python (historical PyO3/tiktoken) – stay on a supported 3.10+ interpreter via pipx/uv or a brew bottle; bleeding-edge system Python fails when wheels lag.
5. OpenRouter 404 on free model – use openrouter/openrouter/free, not openrouter/free. Provider/model split makes the doubled prefix intentional.

Upgrade and uninstall

# upgrade (pick the tool you used)
pipx upgrade gptme
uv tool upgrade gptme
brew upgrade gptme
# or re-run the curl installer

# bleeding edge
pipx install --force "git+https://github.com/gptme/gptme.git"

# uninstall
pipx uninstall gptme
uv tool uninstall gptme
brew uninstall gptme

# leftover config (optional cleanup)
rm -rf ~/.config/gptme

No special migration steps called out for 0.33.0 beyond normal config compatibility. Re-run gptme-doctor after upgrades when extras or browsers drift.

FAQ

What is the latest gptme version I should install?

Stable 0.33.0 on PyPI and Homebrew as of this writing. GitHub dev tags only if you need unreleased fixes.

Do I need an API key on day one?

No. gptme-auth covers ChatGPT Plus/Pro or SuperGrok; OpenRouter free after OAuth; Gemini/Groq free tiers; or OPENAI_BASE_URL → Ollama. When you do have keys, park them under [env] in ~/.config/gptme/config.local.toml so they never sit in a committed config.toml.

pipx install worked but browser and tmux tools feel broken – why?

Base install is bare on purpose. Browser = browser extra plus Playwright binaries (error #2 above). tmux/gh/shellcheck are plain system packages on PATH. gptme-doctor names the gaps; apt/brew for OS tools, then inject or reinstall extras. That’s the gap between “gptme starts” and “agent can browse and hold long jobs.”

Next action: curl -sSf https://gptme.ai/install.sh | sh, then gptme-doctor, then one real task in a throwaway directory – not another docs tab.