Aider is a free, open-source AI pair programmer that runs in your terminal. You tell it what to change in plain English, and it edits the files in your project directly, then commits each change to git with a sensible message so you can review or undo it in seconds.
It works with almost any model: Claude, GPT, Gemini and DeepSeek through their APIs, or fully local models through Ollama, so your code never leaves your PC. It also builds a map of your whole codebase, which is why it copes well with real projects rather than single files.
This guide covers installing Aider on Windows, Mac and Linux, connecting a cloud API or a local Ollama model (including the context-size trap that ruins most local setups), the commands you will use every day, chat modes, config files and fixes for common errors.
Details come from the official Aider docs and GitHub repo, checked in November 2026.
- Install:
python -m pip install aider-installthenaider-install(Python 3.8-3.13), or the one-line installer for your OS. - Run with Claude:
cd your-project, thenaider --model sonnet --api-key anthropic=YOUR_KEY. - Run with DeepSeek:
aider --model deepseek --api-key deepseek=YOUR_KEY. - Run locally: start Ollama with
OLLAMA_CONTEXT_LENGTH=8192 ollama serve, thenaider --model ollama_chat/<model>. - Daily commands:
/add,/drop,/ask,/architect,/undo,/run,/test. - Safety net: every edit is a git commit;
/undoreverts the last one.
What Is Aider?
Aider describes itself as “AI pair programming in your terminal”. You run it inside a git repository, add the files you want to work on, and chat. The model proposes edits, Aider applies them to your files, and it commits the result.
| Feature | What it does |
|---|---|
| Repo map | Builds a compact map of your whole codebase so the model understands how files connect |
| Git integration | Auto-commits each change with a message; diff, review and undo with normal git tools |
| 100+ languages | Python, JavaScript, TypeScript, Rust, Go, C++, PHP, HTML, CSS and many more |
| Lint and test | Runs your linter and tests after edits and can fix what fails |
| Images and web pages | Add screenshots or docs pages as context |
| Voice | Speak your requests instead of typing |
| Editor watch mode | Write instructions as code comments in your IDE and Aider acts on them |
| Any LLM | Cloud APIs or local models via Ollama and other OpenAI-compatible servers |
Aider itself is free. You only pay for API usage if you use a paid model, and local models cost nothing beyond your electricity.
Install Aider
The official docs recommend the aider-install helper, which puts Aider in its own environment (and can install Python 3.12 for it) so it does not clash with your other Python projects.
- Make sure Python is installed (
python --version). aider-install works with Python 3.8 to 3.13. - Run
python -m pip install aider-install - Run
aider-install - Open a new terminal and check it works:
aider --version
| Other install options | Command |
|---|---|
| Mac and Linux one-liner | curl -LsSf https://aider.chat/install.sh | sh |
| Windows PowerShell one-liner | powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 | iex" |
| uv | uv tool install --force --python python3.12 --with pip aider-chat@latest |
| pipx (Python 3.9-3.12) | pipx install aider-chat |
The docs advise against installing Aider through system package managers (apt, brew formulae from third parties and so on), because they often bring the wrong dependencies. You also need git installed, since Aider works inside git repos.
Use Aider With Claude, GPT, Gemini or DeepSeek
Go into your project folder and start Aider with a model alias and your API key:
| Provider | Command |
|---|---|
| Anthropic (Claude Sonnet) | aider --model sonnet --api-key anthropic=YOUR_KEY |
| DeepSeek | aider --model deepseek --api-key deepseek=YOUR_KEY |
| OpenAI | aider --model o3-mini --api-key openai=YOUR_KEY (GPT-5 family models are also supported) |
| Google Gemini | aider --model gemini --api-key gemini=YOUR_KEY |
| OpenRouter | aider --model openrouter/<provider>/<model> with OPENROUTER_API_KEY set |
Aliases such as sonnet, opus, haiku and gemini point to current models and get updated in new releases. To avoid typing keys every time, put them in a .env file or .aider.conf.yml (see below), or set environment variables like ANTHROPIC_API_KEY.
Need a key? See our guides to getting a Claude API key and getting a DeepSeek API key. For which Claude model codes best, read best Claude model for coding.
Use Aider With Local Models (Ollama)
Running Aider with a local model keeps your code completely private. The setup is simple, but there is one trap you must avoid.
- Install Ollama and pull a coding model:
ollama pull <model>. A Qwen coder model is a common choice; pick the largest that fits your VRAM. Our Ollama guide shows how. - Tell Aider where Ollama is. Mac/Linux:
export OLLAMA_API_BASE=http://127.0.0.1:11434. Windows:setx OLLAMA_API_BASE http://127.0.0.1:11434, then open a new terminal. - Start Ollama with a bigger context window:
OLLAMA_CONTEXT_LENGTH=8192 ollama serve(on Windows, setOLLAMA_CONTEXT_LENGTHas an environment variable and restart Ollama). - In another terminal, go to your project and run
aider --model ollama_chat/<model>.
The trap: the Aider docs warn that Ollama’s default context window is only about 2k tokens, and that Ollama silently throws away anything that does not fit. That means the model never sees most of your files and gives strange, broken edits with no error message.
By default, Aider now asks Ollama for enough context to fit each request plus 8k tokens for the reply. To force a fixed size for a model, add this to .aider.model.settings.yml in your home folder or project:
- name: ollama_chat/<model>
extra_params:
num_ctx: 65536
Use the ollama_chat/ prefix, not ollama/; the docs recommend it. Be realistic too: small local models edit code far less reliably than top cloud models. A 30B-class coder on a 24 GB GPU is a sensible minimum for serious work, and you can always switch models mid-session with /model.
Your First Session
- Open a terminal in your project folder. If it is not a git repo yet, Aider offers to create one.
- Start Aider with your model, for example
aider --model sonnet. - Add the files you want changed:
/add app.py utils.py(or pass them on the command line:aider app.py utils.py). - Ask for a change in plain English: Add input validation to the signup function and return a clear error message for each invalid field.
- Aider shows the edits, applies them and makes a git commit.
- Review with
/diff. Not happy? Type/undo. - Run your tests from inside Aider:
/test pytest. If they fail, Aider sees the output and can fix it.
Essential Commands
| Command | What it does |
|---|---|
/add <files> |
Add files Aider may edit |
/read-only <files> |
Add files for reference only |
/drop <files> |
Remove files to free context |
/ask <question> |
Ask about the code without editing |
/code <request> |
Request code changes (default mode) |
/architect <request> |
Plan with one model, edit with another |
/diff |
Show changes since your last message |
/undo |
Revert the last commit Aider made |
/run <cmd> or !<cmd> |
Run a shell command and optionally share output |
/test <cmd> |
Run tests; output is added only if they fail |
/web <url> |
Scrape a page into the chat as markdown |
/model <name> |
Switch the main model |
/tokens |
See how much context you are using |
/clear and /reset |
Clear history; reset also drops all files |
/commit |
Commit edits you made outside Aider |
/ok |
Tell Aider to go ahead with a proposed change |
/help <question> |
Ask about Aider itself |
/exit |
Quit |
Chat Modes: Code, Ask, Architect
| Mode | Use it for |
|---|---|
| Code (default) | Making changes to files |
| Ask | Understanding code, planning, reviewing without touching files |
| Architect | Bigger changes: an “architect” model plans, an “editor” model writes the edits |
| Context | Letting Aider work out which files are relevant |
Switch with /chat-mode, or prefix a single message with /ask or /architect. A good habit: discuss the plan in /ask, then say /code go ahead once you agree.
Config Files and Conventions
.aider.conf.ymlin your home folder or repo root sets defaults (model, auto-commits, lint and test commands) so you can just typeaider..envholds API keys likeANTHROPIC_API_KEY. Keep it out of git..aider.model.settings.ymlsets per-model options such as Ollama’snum_ctx.- Conventions file: write your coding rules (style, libraries to use, test framework) in a markdown file such as
CONVENTIONS.mdand load it with/read-only CONVENTIONS.mdoraider --read CONVENTIONS.md. Our AGENTS.md guide explains how to write rules files that AI coding tools follow. - Turn off auto-commits with
--no-auto-commitsif you prefer to commit yourself.
Use Aider From Your Editor
Start Aider with --watch-files and keep coding in VS Code, JetBrains, Vim or any editor. Add a comment that ends in AI! to ask for a change, for example # add retry logic with exponential backoff AI!, and save.
Aider spots it and makes the edit. A comment ending in AI? asks a question instead.
Tips for Better Results
- Add only the files that need changing. The repo map gives the model the bigger picture; too many added files waste context and money.
- Make small, specific requests. “Add a –dry-run flag to the export command” beats “improve the CLI”.
- Set lint and test commands (
--lint-cmd,--test-cmd,--auto-test) so Aider fixes its own mistakes. - Use architect mode for refactors that touch many files.
- Check
/tokenson long sessions and/dropor/clearwhen it grows large. - Work on a branch so you can throw away an experiment in one command.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
aider not found |
Install path not on PATH yet | Open a new terminal; rerun aider-install |
| Local model gives nonsense edits | Ollama context too small, prompt silently cut | Start Ollama with OLLAMA_CONTEXT_LENGTH=8192 or set num_ctx |
| “Model not recognised” warning | Unknown or misspelled model name | Check the name; for Ollama use ollama_chat/ |
| Edits fail to apply | Model is weak at the edit format | Use a stronger model or architect mode |
| Authentication error | Wrong or missing API key | Check --api-key, .env or environment variables |
| Dependency conflicts after pip install | Installed into a shared Python | Use aider-install, uv or pipx instead |
| High API bills | Too many files added, long chats | Drop files, clear history, use a cheaper model for simple tasks |
| Aider changed the wrong thing | Vague request | /undo, then ask more specifically |
Aider vs Other AI Coding Tools
| Tool | Type | Pick it if |
|---|---|---|
| Aider | Open-source terminal pair programmer | You want any model, local support and git-first workflow |
| Claude Code | Anthropic’s agentic CLI | You use Claude and want a more autonomous agent |
| Gemini CLI / Codex CLI | Vendor CLIs | You are tied to Google or OpenAI |
| Cursor | AI code editor | You prefer a full IDE over the terminal |
Aider’s core releases have slowed compared with 2024-2025, but the main branch keeps adding support for new Claude, GPT and Gemini models. It remains one of the most flexible free options, especially for local models.
My Take
Aider is the tool I would recommend to anyone who wants AI coding help without being locked into one vendor. The git-commit-per-change design makes it safe to experiment, and the same commands work whether you plug in Claude or a local model on your own GPU.
Start with a strong cloud model to learn the workflow, then try a local coder model through Ollama for private projects. Just remember to raise Ollama’s context size first.
FAQ
Is Aider free?
Yes. Aider is open source and free. You pay only for API usage if you use paid models.
Can Aider work offline?
Yes, with a local model through Ollama or another local OpenAI-compatible server.
Which model is best for Aider?
Top cloud models like Claude Sonnet or Opus, GPT-5 models and DeepSeek give the most reliable edits. Aider publishes leaderboards on its website comparing models.
Why does Aider work badly with Ollama?
Usually because Ollama’s default context is about 2k tokens and it silently drops the rest. Start Ollama with OLLAMA_CONTEXT_LENGTH=8192 or higher.
How do I undo an Aider change?
Type /undo to revert the last commit Aider made, or use normal git commands.
Does Aider need git?
Yes, it works inside git repos and offers to create one if needed. You can turn off auto-commits with –no-auto-commits.
Can I use Aider in VS Code?
Yes. Run Aider in the VS Code terminal, or start it with –watch-files and write comments ending in AI! in your code.
What languages does Aider support?
Over 100, including Python, JavaScript, TypeScript, Rust, Go, C++, Java, PHP, HTML and CSS.



