Aider AI Git Commit Setup: Install v0.86.2 in 10 Min

By the end of this guide, your terminal will look like this: you type > rename UserService to AccountService everywhere, hit Enter, and 20 seconds later git log --oneline -1 shows a clean commit authored by you (aider) with a Conventional Commits message the model wrote from the diff. That’s the end state. Let’s walk backwards to the install.

The tool is Aider, an open-source terminal pair programmer. The version we’re installing is aider-chat 0.86.2, the latest stable on PyPI as of February 12, 2026. The reason this article exists: every other tutorial covers the install, then waves at “auto-commits, yay!” – but the AI git commit behavior has three real gotchas you’ll hit within an hour of using it.

System requirements (the Python 3.13 trap)

Here’s where most installs fail on the first try. Per PyPI metadata, aider-chat requires Python >=3.10, <3.13. If your system Python is 3.13 (the default on fresh installs of recent macOS and Ubuntu builds), pip install aider-chat will fail with a setuptools error.

That dependency count isn’t trivia. A community analysis noted aider pulls around 108 packages – which is why installing it into your project’s venv is a bad idea. You’ll get version conflicts within a week.

Think of it like a power tool with its own dedicated outlet. You wouldn’t plug a table saw into the same circuit as your desk lamp and expect both to work fine. Aider needs its own isolated environment, and the recommended install path gives you exactly that.

Install Aider with the recommended path

Use the aider-install wrapper. It bootstraps uv, fetches Python 3.12 if needed, and installs aider in an isolated environment. Only two packages touch your system Python: uv and aider-install itself.

python -m pip install aider-install
aider-install

That second command runs uv tool install --python python3.12 aider-chat behind the scenes and adds aider to your PATH. Done.

If you’re already on Python 3.13 and the wrapper still complains, drop to uv directly:

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

This is the workaround the maintainers themselves recommend in GitHub issue #3037 for Python 3.13 users.

First-time config: pick a model, set a key

cd into a git repo, then launch aider with one model flag and one key. For the cheapest functional setup:

cd ~/code/my-project
aider --model deepseek --api-key deepseek=YOUR_KEY

Swap deepseek for sonnet (Anthropic) or gpt-4o (OpenAI) with the matching key prefix. On first launch aider scans the repo, builds a tree-sitter-powered repo map, and drops you at a prompt.

For persistent config, drop a ~/.aider.conf.yml:

model: sonnet
weak-model: claude-3-5-haiku-20241022
auto-commits: true
attribute-co-authored-by: true
git-commit-verify: true

That last line matters. Per the official git docs, aider passes --no-verify to git by default – your pre-commit hooks don’t run on AI commits unless you set git-commit-verify: true. Linters, secret scanners, conventional-commit validators: all bypassed. One line in your config fixes it.

How the AI commit actually works

Edit staged, weak model receives the diff plus chat history, Conventional Commits subject line comes back, aider commits with --no-verify and appends (aider) to the git author and committer name fields. That’s the whole pipeline in one sentence.

The two-model split is the cost optimization nobody explains. Your main model (Sonnet, GPT-4o, whatever) does the coding. The weak model (Haiku, GPT-4o-mini, DeepSeek Chat) writes the commit message for pennies. Skip setting --weak-model and aider defaults to the main model for both – your commit messages cost the same as your code edits. On a long session, that adds up fast.

Pro tip: Add --attribute-co-authored-by if your team requires human authorship for compliance reasons. Aider appends a Co-authored-by: aider <[email protected]> trailer (per the release notes) instead of overwriting the author field – your commits still count as yours in GitHub’s contribution graph, but the AI involvement is auditable.

Verify the install – and the commit pipeline

Two checks. First, version:

aider --version
# expected: aider 0.86.2

Second, the actual commit test. Make a trivial repo and ask for one edit:

mkdir aider-test && cd aider-test
git init
echo "print('hello')" > hello.py
git add . && git commit -m "initial"
aider hello.py
> add a docstring to the print line
# (aider edits, commits)
git log --oneline -2

You should see two commits: yours, and a second one ending in (aider). If you see only one, auto-commits is disabled. If you see three, aider committed a dirty file before its own edit – that’s the dirty commit behavior, working as intended.

The –no-auto-commits gotchas nobody warns you about

This is the section that doesn’t exist in other tutorials. Three real bugs from the issue tracker:

1. –no-auto-commits silently kills dirty commits too. Running aider --no-auto-commits --dirty-commits sounds like “don’t commit my edits, but do commit pre-existing changes.” In practice (issue #4074, confirmed on v0.83.1), no commits happen at all. Workaround: don’t combine the flags – use --no-auto-commits alone and commit dirty state manually before launching aider.
2. Creating a new file commits anyway. Even with auto-commits off, when aider asks “create and add to git?” and you say yes, it creates an empty-file commit that ignores the flag. Reported in issue #101 and #3600. Workaround: answer “no” to the create prompt and touch the file yourself in another terminal.
3. Pre-commit hooks don’t run – and the failure is invisible. Covered in the config section above. The short version: set git-commit-verify: true or your CI catches what your local commit didn’t.

Common install errors and fixes

Hit one of these? Here’s the actual cause.

• aider: command not found after install – uv installed it to ~/.local/bin which isn’t on PATH. Run uv tool update-shell and restart the terminal, or invoke as python -m aider.
• ImportError mentioning litellm or tree-sitter – you installed via system pip into a venv with conflicting deps. Per aider’s troubleshooting docs, reinstall via aider-install or uv tool install for isolation.
• Aider commits a huge unrelated change as the first commit – that’s the dirty-files behavior. It’s separating your uncommitted work from the AI’s. Annoying once; defensive forever.

Upgrade and uninstall

uv tool upgrade aider-chat
# or, if you used pip:
python -m pip install -U --upgrade-strategy only-if-needed aider-chat

The only-if-needed flag matters here: aider pins specific versions of litellm and related libraries, so a greedy upgrade can break the install. Check the release notes before upgrading on a machine where aider is part of your daily workflow.

Uninstall:

uv tool uninstall aider-chat
rm -rf ~/.aider.conf.yml ~/.aider.chat.history.md ~/.aider.input.history

Those three dotfiles – chat history, input history, global config – live in your home directory. Per-repo equivalents (.aider.chat.history.md, .aider.tags.cache.v3/) sit in each project root. Add them to your global .gitignore before you forget.

FAQ

Can I customize the commit message format?

Yes – pass --commit-prompt on launch or set commit-prompt in .aider.conf.yml. The weak model receives your prompt plus the diff and writes accordingly. Check the current docs for exact syntax, as prompt flag behavior has shifted across releases.

What happens to my session if aider crashes mid-edit?

Say you’re 20 minutes into a refactor across five files. Aider crashes. Because every successful edit was already committed, git log shows exactly how far it got – no lost work, no half-applied diffs sitting in your working tree. You re-launch with the same files added and continue. This is the actual reason the auto-commit default exists; it’s not a feature, it’s a crash-recovery mechanism.

Does aider need internet access for the commit itself?

Only for generating the message. The git commit happens locally – aider shells out to git commit the same way you would. But the message text comes from the weak model API call, so a dropped network connection between the edit and the commit means aider falls back to a generic message. Fully offline? Point --weak-model at an Ollama-served local model.

Now go run aider hello.py in a throwaway repo and watch the second line of git log --oneline appear. That’s the only validation that matters.