Installation Guide

Complete installation instructions for all platforms and environments.

Table of contents

  1. System Requirements
    1. Minimum Requirements
    2. Recommended Requirements
  2. Optional Tools
  3. Installation Methods
    1. Method 1: Using uv (Recommended)
      1. Install uv
      2. Install YOLO Developer
    2. Method 2: Using pip
    3. Method 3: Development Installation
    4. Method 4: Docker Installation
  4. Platform-Specific Instructions
    1. macOS
      1. Prerequisites
      2. Installation
      3. Shell Configuration
    2. Linux (Ubuntu/Debian)
      1. Prerequisites
      2. Installation
      3. Shell Configuration
    3. Windows (WSL2)
      1. Prerequisites
      2. Installation
      3. Accessing from Windows
  5. Post-Installation Setup
    1. 1. Configure API Keys
    2. 2. Verify Installation
    3. 3. Initialize Your First Project
    4. Brownfield Setup (Existing Repo)
  6. Upgrading
    1. Upgrade to Latest Version
    2. Check for Updates
  7. Uninstallation
    1. Remove YOLO Developer
    2. Remove uv (Optional)
  8. Troubleshooting Installation
    1. Python Version Issues
    2. Permission Denied
    3. ChromaDB Build Errors
    4. SSL Certificate Errors
    5. uv Not Found
  9. Next Steps

System Requirements

Minimum Requirements

Component Requirement
Python 3.10 or higher
Memory 4 GB RAM
Disk Space 500 MB
OS macOS 12+, Ubuntu 20.04+, Windows 10+ (WSL2)
Component Requirement
Python 3.12
Memory 8 GB RAM
Disk Space 2 GB (for memory persistence)
OS macOS 14+, Ubuntu 22.04+

Optional Tools

These are only required if you plan to use GitHub automation commands.

  • GitHub CLI (gh): Install from https://cli.github.com/ and run gh auth login.

Installation Methods

uv is a fast Python package manager that handles dependencies efficiently.

Install uv

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Homebrew (macOS):

brew install uv

Install YOLO Developer 

# Clone repository
git clone https://github.com/bbengt1/yolo-developer.git
cd yolo-developer

# Install dependencies
uv sync

# Verify installation
uv run yolo --version

Expected output:

YOLO Developer v0.1.0

Method 2: Using pip

If you prefer traditional pip installation:

# Clone repository
git clone https://github.com/bbengt1/yolo-developer.git
cd yolo-developer

# Create virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# Install dependencies
pip install -e .

# Verify installation
yolo --version

Method 3: Development Installation

For contributors and developers:

# Clone repository
git clone https://github.com/bbengt1/yolo-developer.git
cd yolo-developer

# Install with all development dependencies
uv sync --all-extras

# Install pre-commit hooks (optional)
uv run pre-commit install

# Verify development tools
uv run pytest --version
uv run mypy --version
uv run ruff --version

Method 4: Docker Installation

Docker support is coming soon. This section will be updated when available.

# Pull the image
docker pull ghcr.io/bbengt1/yolo-developer:latest

# Run with mounted project
docker run -v $(pwd):/project -e YOLO_LLM__OPENAI__API_KEY=$OPENAI_API_KEY \
  ghcr.io/bbengt1/yolo-developer yolo init

Platform-Specific Instructions

macOS

Prerequisites

  1. Install Xcode Command Line Tools: 
    xcode-select --install
  2. Install Python 3.10 - 3.13 (if not already installed): 
    # Using Homebrew
brew install python@3.12

# Verify
python3 --version
  3. Install uv: 
    brew install uv

Installation 

git clone https://github.com/bbengt1/yolo-developer.git
cd yolo-developer
uv sync

Shell Configuration

Add to your ~/.zshrc or ~/.bashrc:

# YOLO Developer API Keys
export YOLO_LLM__OPENAI__API_KEY="sk-proj-..."
export YOLO_LLM__ANTHROPIC_API_KEY="sk-ant-..."

# Optional: Add yolo to PATH if using pip install
export PATH="$HOME/yolo-developer/.venv/bin:$PATH"

Reload shell:

source ~/.zshrc

Linux (Ubuntu/Debian)

Prerequisites

  1. Update system packages: 
    sudo apt update && sudo apt upgrade -y
  2. Install Python 3.10 - 3.13: 
    sudo apt install python3.12 python3.12-venv python3-pip -y

# Verify
python3 --version
  3. Install uv: 
    curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Installation 

git clone https://github.com/bbengt1/yolo-developer.git
cd yolo-developer
uv sync

Shell Configuration

Add to your ~/.bashrc:

# YOLO Developer API Keys
export YOLO_LLM__OPENAI__API_KEY="sk-proj-..."
export YOLO_LLM__ANTHROPIC_API_KEY="sk-ant-..."

Reload:

source ~/.bashrc

Windows (WSL2)

YOLO Developer requires WSL2 on Windows. Native Windows support is not available.

Prerequisites

  1. Enable WSL2: 
    # Run in PowerShell as Administrator
wsl --install

  2. Install Ubuntu from Microsoft Store

  3. Open Ubuntu terminal and update: 
    sudo apt update && sudo apt upgrade -y
  4. Install Python: 
    sudo apt install python3.12 python3.12-venv -y
  5. Install uv: 
    curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Installation 

git clone https://github.com/bbengt1/yolo-developer.git
cd yolo-developer
uv sync

Accessing from Windows

Your WSL2 files are accessible at:

\\wsl$\Ubuntu\home\<username>\yolo-developer

Post-Installation Setup

1. Configure API Keys

Never commit API keys to version control. Always use environment variables.

Option A: Environment Variables (Recommended)

export YOLO_LLM__OPENAI__API_KEY="sk-proj-..."

Option B: .env File (Local Development)

Create .env in your project root:

YOLO_LLM__OPENAI__API_KEY=sk-proj-...
YOLO_LLM__ANTHROPIC_API_KEY=sk-ant-...

Add .env to your .gitignore file.

2. Verify Installation

Run the verification command:

uv run yolo --version
uv run yolo config show

Expected output:

YOLO Developer v0.1.0

project_name: null
llm:
  provider: auto
  cheap_model: gpt-5.2-instant
  premium_model: claude-sonnet-4-20250514
  best_model: claude-opus-4-5-20251101
  openai_api_key: "**********" (configured)
  anthropic_api_key: "**********" (configured)
  openai:
    code_model: gpt-5.2-pro
  hybrid:
    enabled: false
quality:
  test_coverage_threshold: 0.8
  gate_pass_threshold: 0.7
memory:
  persist_path: .yolo/memory
  vector_store_type: chromadb
  graph_store_type: json

3. Initialize Your First Project 

cd /path/to/your/project
uv run yolo init --name my-project

Brownfield Setup (Existing Repo) 

cd /path/to/existing/project
uv run yolo init --brownfield

To scan without making changes:

uv run yolo init --brownfield --scan-only

Upgrading

Upgrade to Latest Version 

cd yolo-developer
git pull origin main
uv sync

Check for Updates 

git fetch origin
git log HEAD..origin/main --oneline

Uninstallation

Remove YOLO Developer 

# Remove the repository
rm -rf /path/to/yolo-developer

# Remove project data (in each project)
rm -rf .yolo/
rm yolo.yaml

Remove uv (Optional) 

rm -rf ~/.cargo/bin/uv

Troubleshooting Installation

Python Version Issues

Problem: Python 3.10 - 3.13 required

Solution:

# Check installed versions
python3 --version
which python3.12

# Use specific version with uv
uv python install 3.12
uv sync

If uv still selects an unsupported interpreter, pin it explicitly:

uv sync --python 3.13 --all-extras
uv run --python 3.13 yolo --help

Permission Denied

Problem: Permission denied when installing

Solution:

# Don't use sudo with uv
# Instead, ensure ~/.local/bin is in PATH
export PATH="$HOME/.local/bin:$PATH"

ChromaDB Build Errors

Problem: Failed to build chromadb

Solution (Ubuntu):

sudo apt install build-essential python3-dev
uv sync

Solution (macOS):

xcode-select --install
uv sync

SSL Certificate Errors

Problem: SSL: CERTIFICATE_VERIFY_FAILED

Solution (macOS):

# Run the certificate installer
/Applications/Python\ 3.12/Install\ Certificates.command

uv Not Found

Problem: command not found: uv

Solution:

# Add to PATH
export PATH="$HOME/.cargo/bin:$PATH"

# Or reinstall
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Next Steps

After successful installation:

  1. Getting Started - Quick start guide
  2. Configuration - Customize your setup
  3. CLI Reference - Learn all commands

Back to top

Copyright © 2024-2026 YOLO Developer. Distributed under the MIT License.