Skip to content
Get packs

Guide · Open source

How to use PentestGPT: install, run and tips

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

PentestGPT is an open-source Python tool that uses large language models to assist security testing. Its main mode runs an autonomous agent that drives Claude Code or Codex through staged phases. This guide shows you how to install it, start a session and understand what it does, and it is written for readers with a security or command-line background who have permission to test their targets.

PentestGPTGreyDGL/PentestGPT · ★ 16.2k · MIT

Quick start

  1. 1Check prerequisites. Confirm Python 3.12+ and uv are available, and that the Claude Code CLI or Codex CLI is installed and logged in.
  2. 2Clone the repository. Run git clone https://github.com/GreyDGL/PentestGPT.git to download the source.
  3. 3Enter the project folder. Change into the PentestGPT directory with cd PentestGPT.
  4. 4Install dependencies. Run make install, which runs uv sync.
  5. 5Confirm you have permission. Only run PentestGPT against systems you are explicitly authorized to test, such as CTF machines or your own lab.
  6. 6Start a session. Run pentestgpt --target with your target, optionally adding --instruction for context and --mode pentest for a penetration test.

What you need before you install PentestGPT

PentestGPT needs Python 3.12 or newer, the uv Python package manager, and either the Claude Code CLI (claude) or the Codex CLI (codex). Both CLIs must be installed and authenticated before you run the tool for local Claude or Codex runs.

  • Python 3.12+
  • uv (Python package manager)
  • Claude Code CLI or Codex CLI, installed and authenticated

Install PentestGPT from source

The project is installed by cloning the repository and running make install, which runs uv sync to install dependencies.

git clone https://github.com/GreyDGL/PentestGPT.git cd PentestGPT make install # runs uv sync

Run your first CTF session

CTF mode is the default. Pass a target with --target. You can add context with --instruction, for example a note about the technology the target uses.

  • Use --mode pentest to switch to the penetration-test pipeline.
  • Use --list-sessions to see saved sessions.
pentestgpt --target 10.10.11.234 pentestgpt --target 10.10.11.50 --instruction "WordPress site, focus on plugin vulnerabilities" pentestgpt --target 10.10.11.234 --mode pentest pentestgpt --list-sessions

Understand the multi-stage pipeline

The agent works through staged phases, feeding each stage's findings into the next. For CTF challenges the stages are recon, exploit and walkthrough. For penetration tests they are asset discovery, vulnerability identification and report. The Live Walkthrough feature tracks steps as the agent works, and sessions can be saved and resumed.

  • CTF: recon → exploit → walkthrough
  • Pentest: asset discovery → vulnerability identification → report

Run PentestGPT in Docker

A Docker image bundles the tool with the Claude Code and Codex CLIs. You log in once, and sessions persist in named volumes so you do not re-login on later runs. Logins persist across container recreation; make docker-down keeps them, while make docker-nuke removes the login volumes.

make docker-build make docker-login make docker-auth-status make docker-run TARGET=10.10.11.234 BACKEND=claude MODEL=opus MODE=pentest

Use the interactive legacy mode with other LLM providers

pentestgpt-legacy is the classic human-in-the-loop mode from the USENIX 2024 paper. It keeps you in control and talks to several providers, including OpenAI, Anthropic, Google Gemini, DeepSeek, xAI, Qwen, Moonshot and local Ollama. You enable a provider by setting its API key in your environment or .env file. Only configured providers are enabled.

  • Use --list-models to see every supported model and which providers are configured.
  • Use --smoke-test to round-trip each configured model and print a pass/fail matrix.
  • Ollama is used through an OpenAI-compatible base URL.
pentestgpt-legacy pentestgpt-legacy --reasoning-model claude-opus-4-8 --parsing-model gemini-3.5-flash pentestgpt-legacy --reasoning-model ollama:qwen3 --base-url http://localhost:11434/v1 pentestgpt-legacy --list-models pentestgpt-legacy --smoke-test

What people use it for

  • Working through CTF challenges across web, crypto, reversing, forensics, PWN and privilege escalation categories.
  • Running an AI-assisted penetration test on targets you are authorized to assess, following the asset discovery to report pipeline.
  • Studying LLM-driven penetration testing as a research subject, based on the USENIX Security 2024 paper.
  • Using a local Ollama model in the interactive legacy mode for experiments.

Frequently asked questions

Is PentestGPT free to use?

PentestGPT is published under the MIT licence, as listed on its repository. The LLM providers you connect to, such as Claude Code, Codex or API keys for other providers, may have their own costs and terms.

What are the requirements for PentestGPT?

The README lists Python 3.12+, the uv package manager, and the Claude Code CLI or Codex CLI installed and authenticated. The legacy mode needs an API key for each provider you want to use, or a local Ollama setup.

How do I install PentestGPT?

Clone the GitHub repository, change into the PentestGPT folder, and run make install. The Docker option uses make docker-build and make docker-login instead.

Can I use PentestGPT with local models?

Yes, in the legacy mode. The README shows pentestgpt-legacy with an ollama: model name and an OpenAI-compatible base URL such as http://localhost:11434/v1.

What are the alternatives to PentestGPT?

The comparable projects listed for this item are Nebula, PentestAgent and cybersecurity LLM agents from academic projects. Compare them on the models they support, the workflow they follow and how much review their output needs.

Why does PentestGPT give wrong results sometimes?

Agent output depends on the underlying model and may be wrong, so results need expert review. Check every finding yourself before acting on it, and do not treat the tool as a guaranteed or audited scanner.

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

PentestGPT suits security students working through CTFs, professionals running authorized AI-assisted pentests, and researchers who already have Claude Code or Codex set up. It is not a good fit for beginners without security or command-line background, for testing anything you lack explicit permission to test, or for teams that need a guaranteed, audited scanner.

Install options & downloads