Installation & First Pair

Aider is a Python package you install once and run on any git repository. It works with Claude, GPT, Gemini, DeepSeek, and local models through Ollama. The first pairing session is five minutes: pick a repo, add the files you want to edit, describe the change, and watch Aider write the code.

What you'll learn

• Install with pip install aider-chat, uv tool install aider-chat, or pipx install aider-chat
• Aider requires a git repository to work. It will offer to create one if you launch it outside a repo
• aider <file1> <file2> launches Aider with those files added to the chat session for editing
• You need an API key for at least one provider: OpenAI, Anthropic, Gemini, DeepSeek, or a local model via Ollama
• Aider auto-commits every change with a descriptive message. Your history is never ambiguous

The problem

AI coding tools tend to be heavyweight. IDEs with panels, browser interfaces, Docker daemons. Aider is different: one binary, one terminal window, one git repo. The cost of that simplicity is that you need to know which files to add and which model to use before you start. This lesson covers every install path, the first pairing session on a real repo, and the common failures that stop people before they get to their first edit.

Options & when to use each

Install method	Good for	Costs you	When to pick it
pip (pip install aider-chat)	Any Python environment	May conflict with other packages in your global Python	You have Python 3.10+ and want the simplest path
uv (uv tool install aider-chat)	Clean, isolated installs	Requires uv to be installed separately	You want an isolated tool environment without pipx
pipx (pipx install aider-chat)	Isolated tool installs, no venv management	Requires pipx, which requires pip	You install all CLI tools this way and want isolation from your project venvs
Docker (docker run ...)	Servers, CI, machines without Python	Slower startup, volume mount complexity	You cannot or prefer not to install Python packages on the host

For this course, use pip. Aider targets Python 3.10+ and installing globally with pip is the path most users take. If you hit dependency conflicts, switch to pipx.

Build it

Step 1: Check your Python version

Aider requires Python 3.10 or later. Check what you have:

python3 --version

If you see 3.9.x or earlier, upgrade Python. The fastest path on Ubuntu/Debian:

sudo apt update && sudo apt install python3.11 python3.11-venv

Or use pyenv to manage your Python versions. This allows you to install and set a compatible version globally without affecting system packages.

pyenv install 3.11
pyenv global 3.11

Step 2: Install Aider

Pick one of these three commands:

# Option A: pip (recommended)
pip install aider-chat

# Option B: uv
uv tool install aider-chat

# Option C: pipx
pipx install aider-chat

Verify the install by checking the installed version. Ensure the binary is accessible in your system path.

aider --version

You should see a version number like 0.80.0 or higher. If you get command not found, the pip bin directory may not be on your PATH. Restart your shell or add it:

# Find where pip installed the binary
python3 -m site --user-base
# Typically ~/.local/bin -- add it to PATH if missing
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Step 3: Set your API key

Aider needs an API key for at least one provider. The simplest path is to set it as an environment variable:

# For Anthropic (recommended for best results)
export ANTHROPIC_API_KEY="sk-ant-..."

# For OpenAI
export OPENAI_API_KEY="sk-..."

# For Gemini
export GEMINI_API_KEY="..."

# For DeepSeek
export DEEPSEEK_API_KEY="..."

Add the export line to your ~/.bashrc or ~/.zshrc so it persists across sessions.

You can also store keys in a .env file at the root of your git repo. Aider reads .env automatically:

# .env at your repo root
ANTHROPIC_API_KEY=sk-ant-...

Step 4: Create a practice repo

Aider needs a git repository. Create one now:

mkdir -p ~/aider-practice && cd ~/aider-practice
git init

Aider would also offer to run git init for you if you launched it in a directory without a repo, but doing it yourself gives you control.

Step 5: Launch your first pairing session

Start Aider with a file you want it to edit. If the file doesn't exist yet, Aider will create it:

aider app.py

You will see something like:

Aider v0.80.0
Model: anthropic/claude-sonnet-4-20250514 with diff edit format
Git repo: .git with 1 files
Repo-map: using 1024 tokens
Use /help to see in-chat commands, run with --help to see cmd line args
>

The > prompt is where you describe what you want. Try your first task:

> Write a Flask web app with a single route at / that returns a JSON greeting with the current server time

Aider will read app.py (empty, since it just created it), write the Flask app, and auto-commit:

app.py
>>>>>>> SEARCH (not found)
=======
from flask import Flask, jsonify
from datetime import datetime

app = Flask(__name__)

@app.route('/')
def greeting():
    return jsonify({
        "greeting": "Hello from Aider",
        "time": datetime.now().isoformat()
    })

if __name__ == '__main__':
    app.run(debug=True)
<<<<<<< REPLACE

Applied edit to app.py
Commit 1a2b3c4 aider: Write a Flask web app with greeting endpoint and server time

The commit happened automatically. You did not ask for it. That is Aider's default: every change is committed with a descriptive message.

Step 6: Add more files and iterate

Now add a test file to the chat:

> /add test_app.py

Aider adds test_app.py to the session. The file does not exist yet; Aider will create it when you ask. Now ask for tests:

> Write pytest tests for the greeting endpoint. Test that it returns 200, that the response is JSON, and that 'greeting' is in the response

Aider creates test_app.py, writes the tests, and commits. Two commits in two prompts. The session history is tracked in .aider.chat.history.md so you can review the full conversation later.

Step 7: Choose your model

Aider defaults to a model it knows works well for code editing. You can override this at launch:

# Use Claude Sonnet
aider --model sonnet app.py

# Use GPT-4o
aider --model gpt-4o app.py

# Use DeepSeek
aider --model deepseek app.py

# Use a local model via Ollama
aider --model ollama/llama3.1 app.py

Or switch models mid-session with the /model command:

> /model gpt-4o

Aider switches the model and continues the session with all context preserved.

What goes wrong

Mistake	How you notice it	The fix
aider: command not found	Shell cannot find the binary after install	source ~/.bashrc or add ~/.local/bin to PATH. Restart your terminal
No API key set	Aider asks for a key on startup or fails with an authentication error	Export the key as an environment variable or create a .env file in your repo root
Launching outside a git repo	Aider prints "No git repository found" and offers to create one	Run git init first, or say yes when Aider offers to do it. Aider cannot track changes without git
Wrong model selected	Aider uses GPT-3.5 or a model that produces poor edits	Use --model sonnet or --model gpt-4o at launch. Check the model name at the top of the Aider startup banner
Adding too many files at once	Aider is slow to respond or produces confused edits	Only add the files you need to edit. Aider's repomap will provide context about the rest of the codebase. /drop files you do not need
Python version too old (3.9 or earlier)	pip install fails with dependency resolution errors	Upgrade to Python 3.10+ using pyenv, apt, or your system package manager
Permission denied on pip install	EACCES error writing to system site-packages	Use pip install --user aider-chat to install in your home directory, or use pipx for isolation
Using a model without sufficient context window	Aider truncates or summarizes too aggressively	Use a model with a larger context window (Claude Sonnet, GPT-4o, Gemini Pro) or use /clear to reset the chat

Confirm it worked

Run this sequence. If every step succeeds, Aider is installed and pairing:

# 1. Create a fresh repo
mkdir -p /tmp/aider-test && cd /tmp/aider-test && git init

# 2. Launch Aider on a new file
aider --model sonnet --yes-always hello.py -p "Write a Python script that prints 'Aider is working' and the current date/time"

# 3. Check the file was created and committed
cat hello.py
git log --oneline

If hello.py contains the script and git log shows a commit with a descriptive message, Aider is installed, authenticated, and editing code. That is the baseline for every lesson that follows.

Next: Git Workflow & Commits