Skip to main content

​
Prerequisites

PDD requires Python 3.12 or higher. Check your version before installing: 
python3 --version
1

Install Xcode Command Line Tools

Required for Python compilation:
xcode-select --install
2

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
After installation, add Homebrew to your PATH:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile && eval "$(/opt/homebrew/bin/brew shellenv)"
3

Install Python (if needed)

# Check your version first
python3 --version

# If not found or below 3.12, install via Homebrew
brew install python

​
Install PDD

uv provides faster installs, automatic environment setup, and better isolation than pip.
1

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh
You may need to restart your terminal or source your shell profile for the uv command to become available.
2

Install PDD

uv tool install pdd-cli
Installing via uv tool install ensures:
  • Faster installs with optimized dependency resolution
  • Automatic environment setup without manual configuration
  • Proper handling of the PDD_PATH environment variable
  • Better isolation from other Python packages

​
Alternative: pip

pip install pdd-cli
If you get a permission error, use pip install --user pdd-cli to install into your user directory.

​
Virtual environment

If you prefer to keep PDD isolated in a virtual environment: 
python -m venv pdd-env
source pdd-env/bin/activate
pip install pdd-cli

​
Verify installation

pdd --version
If the command is not found, add the uv tools directory to your PATH: 
export PATH="$HOME/.local/bin:$PATH"
Add this line to your ~/.bashrc or ~/.zshrc to make it permanent.

​
Post-install setup

Run the interactive setup wizard immediately after installation: 
pdd setup
The wizard runs through six steps:
  1. Detects agentic CLI tools (Claude Code, Gemini CLI, Codex CLI) and offers installation and API key configuration
  2. Scans for API keys across .env, ~/.pdd/api-env.*, and your shell environment — prompts you to add one if none are found
  3. Configures models from a reference list of top-rated models across all LiteLLM-supported providers based on your available keys
  4. Optionally creates a .pddrc project config
  5. Tests the first available model with a real LLM call
  6. Prints a structured summary of CLIs, keys, models, and the test result
After setup completes, source the API environment file so your keys take effect in the current terminal session:
source ~/.pdd/api-env.zsh   # or api-env.bash, depending on your shell
New terminal windows load keys automatically.
You can re-run pdd setup at any time to update keys, add providers, or reconfigure settings. If you skip setup, the first regular pdd command you run will detect the missing configuration and print a reminder banner.

​
Auto-update control

PDD automatically updates itself to keep you on the latest version. Control this with the PDD_AUTO_UPDATE environment variable: 
# Disable auto-updates
export PDD_AUTO_UPDATE=false

# Re-enable auto-updates (default)
export PDD_AUTO_UPDATE=true
Add this to your shell config file (.bashrc, .zshrc) for a persistent setting. Disabling auto-updates is useful in CI/CD pipelines and production environments where version stability is required.

​
Shell completion

PDD includes shell completion support, configured automatically by pdd setup. Completion enables tab-completion for commands and flags in your terminal.

​
Next steps

Quickstart

Run your first prompt-to-code workflow in minutes

Command reference

Browse every command, flag, and option

Build docs developers (and LLMs) love

Get started for freeTalk to us