Aider AI Coding Assistant: Install & Use Guide (2026)

Quick answer: Aider is a terminal-based AI pair programmer that edits files in a Git repository. The useful part is not that it can produce code; plenty of tools can do that. Aider’s advantage is the workflow around the code: narrow file context, visible diffs, ordinary Git commits and a straightforward way back when a change is wrong.

The sensible first run is deliberately boring: install Aider in its own environment, create a clean branch, add only the files needed for one small task, inspect the patch and run the repository’s real checks. Do not start with authentication, billing or a production migration.

Verification scope: checked 11 August 2026 against Aider’s official installation, usage, commands, Git, configuration and troubleshooting pages, plus the published PyPI package metadata. This is a documentation-verified guide, not a claim that every command was tested on every operating system or model provider.

What Aider does

Aider is the coding interface, not the language model. It connects to a model provider you choose, gives that model the relevant code context, applies proposed edits to local files and normally records those edits as Git commits. Its repository map supplies compact context about related code without requiring every file to be added to the chat.

If you use Codex or Claude Code instead, NanoNets Graft adds a reusable local codebase map that those agents can consult between sessions.

Aider can speed up bounded changes, but it does not guarantee correct or secure code. Treat its output like a change from another contributor: review it, run checks and understand it before merging or deploying.

What you need before installing Aider

Version note: PyPI listed aider-chat 0.86.2 as the current published package when this guide was checked. Its package metadata requires Python 3.10-3.12. The separate aider-install bootstrapper accepts an existing Python 3.8-3.13 and can install Python 3.12 for Aider, which is why the two version ranges look different. Confirm what you actually installed with aider --version.

• Python: the recommended aider-install route accepts an existing Python 3.8–3.13 and can install a separate Python 3.12 for Aider.
• Git: Aider can offer to create a repository, but starting with an existing clean Git repo provides its main review and undo safeguards.
• A model connection: most cloud models require a separate API account and billing. A consumer chat subscription does not automatically include API use.
• A small first task: choose a change with a clear expected result and relevant tests.

How to install Aider safely

Aider’s current installation page recommends an isolated installer. This reduces dependency conflicts with the Python packages used by your own project.

python -m pip install aider-install
aider-install

Confirm the installed command and read the options supported by your exact build:

aider --version
aider --help

If the shell cannot find aider, reopen the terminal after installation and try Aider’s documented fallback:

python -m aider

Alternative isolated installs

Aider also documents uv and pipx. These are useful when the quick installer does not suit your environment.

# uv
python -m pip install uv
uv tool install --force --python python3.12 --with pip aider-chat@latest

# or pipx
python -m pip install pipx
pipx install --python python3.12 aider-chat

Use the package name aider-chat, not aider. Python 3.12 is the least surprising interpreter choice for the current package. A direct pip install belongs in a virtual environment, and Aider warns that some operating-system package managers can install incompatible dependencies.

Connect a current model without exposing an API key

Model names, prices, rate limits and provider data terms change faster than installation instructions. Discover current names from your installed Aider build:

aider --list-models openai/
aider --list-models anthropic/
aider --list-models gemini/
aider --list-models openrouter/

Then launch with the exact model identifier shown:

aider --model <exact-model-name>

Do not inherit a model name from an old tutorial. Aider’s aliases and model metadata move as providers release and retire models. Search the identifiers supported by your installed build, then check Aider’s current code-editing leaderboard, the provider’s price page and its data-handling terms. If you are considering an OpenAI model, the site’s OpenAI API cost calculator can help estimate spend, but the provider’s official price page remains the final source.

Store keys in a private environment file

Aider accepts environment variables, a private .env file and supported configuration settings. Avoid putting a key directly in a command because it can remain in shell history or process listings.

# .env — use only the provider you need
OPENAI_API_KEY=replace_with_your_real_key
# ANTHROPIC_API_KEY=replace_with_your_real_key
# GEMINI_API_KEY=replace_with_your_real_key
# OPENROUTER_API_KEY=replace_with_your_real_key

Add the real file to .gitignore before saving a key:

.env
.env.*
!.env.example

Aider can load .env files from your home directory, the Git root and the current directory; later files take priority. If the wrong provider account appears, inspect these locations and use /settings without publishing the secret.

Start Aider in a clean Git branch

Run Aider from the project folder. Check the working tree first, then create a task-specific branch:

cd /path/to/your/project
git status
git switch -c aider/small-change
aider --model <exact-model-name>

By default, Aider automatically commits its edits. It can also commit pre-existing dirty changes before editing so your work remains separate. Review any existing changes yourself before starting; a clean branch makes the history much easier to understand.

If your repository relies on pre-commit hooks, note that Aider normally skips them for its own commits. Start it with --git-commit-verify when those hooks must run.

A practical first Aider session

Add only the files likely to be edited. Too much irrelevant code increases model cost and can make the task less clear.

/add src/parser.py tests/test_parser.py
/ask Review parse_age() and explain the smallest change needed to reject negative values. Do not edit files.
/code Implement that change only and add focused tests.
/diff
/test python -m pytest

This separates planning from editing, sets a narrow boundary and ends with an observable check. Replace the example files, function and test command with those used by your project.

Essential Aider commands

/undo is not a general Git rollback. It is designed for the last commit Aider made in the current chat and can refuse pushed commits or conflicting uncommitted work. Inspect /diff, git status and the history before using it.

Review, test and keep changes safely

1. Ask for one bounded change.
2. Read the explanation and every changed file.
3. Use /diff to inspect the exact patch.
4. Run the formatter, linter, type checker and test suite used by the repository.
5. Check dependency files, migrations, permissions and configuration separately.
6. Use /undo if the eligible Aider commit should be discarded.
7. Review the final Git history before pushing, merging or deploying.

A green unit test is useful evidence, not proof that the change is secure or ready for production. Keep human review in the loop for authentication, payments, infrastructure, database migrations and other high-impact code.

Privacy and security checklist

• Know what leaves the computer. A terminal tool can still send selected files, chat messages, command output and repository-map context to a remote provider.
• Follow workplace rules. Do not send employer, client or regulated code to an external service without the required approval.
• Exclude secrets. Keep keys, production credentials, customer data and private certificates out of prompts and editable files.
• Limit scope. Use .aiderignore, Git ignore rules and --subtree-only where appropriate, but do not treat ignore rules as secret storage.
• Inspect commands. /run, /test, /git, linters and hooks execute local commands.
• Avoid blanket approval. Do not use --yes-always when the repository or generated commands are not fully trusted.
• Keep SSL verification on. Do not use --no-verify-ssl as a routine connection fix.
• Protect local histories. Chat histories and troubleshooting logs can contain confidential project details even when they contain no API key.

Example .aiderignore patterns:

.env
.env.*
secrets/
*.pem
*.key
build/
dist/

Troubleshooting common Aider problems

Aider is not recognised

Restart the terminal, run python -m aider, or reinstall with aider-install, uv or pipx. Avoid mixing Aider’s pinned packages into the Python environment used by your application.

Authentication or model-not-found error

• Confirm the correct provider environment variable is set.
• Check whether another .env or config file overrides it.
• Run aider --list-models PROVIDER/ and copy an exact current name.
• Check provider account access, balance and rate limits.
• Use /settings for configuration details, but remove secrets before sharing logs.

The model answers but does not edit

Use /ls to confirm the intended file is in the session, add it with /add, and use /code rather than /ask. Read startup warnings: some models can discuss code but cannot reliably return the structured edits Aider needs.

The session is using too much context

Use /tokens, remove irrelevant files with /drop, and clear old conversation history when it no longer helps. Do not add the entire repository when Aider’s repository map can provide compact surrounding context.

Tests keep failing

Run the narrow failing test first and confirm the test command itself is valid. Give the non-zero result to Aider with /test COMMAND. If repeated edits make the patch worse, review /diff and use /undo instead of continuing indefinitely.

Frequently asked questions

Is Aider free?

Aider is open source under the Apache 2.0 licence. A remote model provider may charge separately for API use. Check its current pricing and do not assume a consumer chat subscription covers API calls.

Does Aider upload the whole repository?

Aider sends the model the files and chat context needed for the task and a compact repository map. That is not necessarily every source file verbatim, but repository information can still leave the computer when you use a hosted provider.

Can Aider use a local model?

Yes. Aider supports Ollama and OpenAI-compatible local endpoints. Results depend on the model’s editing ability, available hardware and configured context window. Local operation is only private when no remote fallback or external endpoint is involved.

Which model should I choose?

There is no permanent answer. Use aider --list-models, check Aider’s current model guidance, and compare editing quality, price, data policy and rate limits. Test the choice on a small branch before using important code.

Is Aider worth using?

Yes, when the job fits in a reviewable patch. Aider gives a coding model enough context to be useful while leaving the result in ordinary files and Git history. That is a much healthier boundary than treating an AI response as finished software.

I would start with a bug that already has a failing test, a small refactor or a documentation change. I would not make an unreviewed first session responsible for credentials, permissions, payments, destructive database work or a production deployment. The tool is at its best when the human can describe the finish line and check whether the code crossed it.

Official Aider sources

• Installation
• Usage
• In-chat commands
• Git integration
• API-key configuration
• Configuring a .env file
• Dependency troubleshooting
• Repository map
• Connecting to models
• Published package and Python requirements
• Release history