Aider with a local model: private AI pair programming with Ollama (Linux, Windows, Mac)

What you get in one minute#

Aider is an open-source AI pair programmer that runs in your terminal, edits the files in your git repo and commits each change, and with Ollama it can use a model that runs on your own computer, so your code does not have to leave the machine.

Logo: the official Aider project (github.com/Aider-AI/aider)

Aider suits people who already work in a terminal and a git repo. This guide uses the local route: Aider talks to Ollama on 127.0.0.1, so your prompts and files stay on your computer. The most common failure is the context window: Ollama's default is small and drops anything beyond it without telling you.

At a glance:

• What it is: a command-line tool; you run aider in a project folder and chat with it.
• What it changes: files in your repo. Each change becomes a git commit you can undo with /undo.
• Local model: through Ollama, on your machine, on port 11434 by default.
• The one setting to get right: the context window. Set it yourself and check it with ollama ps.
• Privacy: with a local model, code and prompts stay on your computer. Analytics are opt-in and can be turned off.
• Status: alive and open source, but releases have slowed: the newest PyPI release is from February 2026 and the last commit on the main branch is from May 2026.

How it fits together#

Aider sits between you, your repo and the model. Everything below the dashed line is optional.

Drawn from the Aider docs (Ollama, git, analytics pages) and the Ollama FAQ, October 2026. Green is the path that stays on your machine; red only happens if you configure a cloud model.

Before you start#

You need Python, git, and Ollama. Aider's own documentation does not publish a RAM or disk minimum; the model you pick decides both, and Ollama's context setting adds memory (see Performance).

Python: install Python 3.10, 3.11 or 3.12. The package metadata on PyPI says it does not run on 3.13, and the one-command installer below installs Python 3.12 for you if needed. Check with:

python3 --version

python --version

Git: check with git --version. Git needs a name and email before it can commit:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Checklist before you install:

• [ ] Python 3.10 to 3.12 available
• [ ] git installed, and your project is a git repo
• [ ] No uncommitted work you care about in that project (Aider commits your pending changes first, see Git auto-commits)
• [ ] Ollama installed; port 11434 free (its default)
• [ ] Enough memory for the model you plan to use (not documented by Aider; check the model page on ollama.com)

Platform support: the official installer covers Mac, Linux and Windows, so all three are covered below. This guide does not teach Docker: the Aider docs name two Docker images but publish no version tag, so there is no pinned image to recommend.

Not run by DIY Lab Hub. Every command and value here comes from the official docs and the sources listed at the end, read in October 2026.

Step 1: Install Ollama and confirm it runs#

Ollama is the local model server. If you already run it, skip to Step 2. Our Ollama guide goes deeper.

Linux#

curl -fsSL https://ollama.com/install.sh | sh

Windows (PowerShell)#

Download the Windows installer from ollama.com/download and run it. Ollama on Windows runs from the tray.

Mac (Terminal)#

Download the Mac app from ollama.com/download and open it once.

Check it worked. Open a new terminal and run:

ollama ps

With no model loaded it prints only the column headings. Ollama's FAQ shows the full layout when a model is loaded (expected output, from the docs):

NAME        ID            SIZE    PROCESSOR   UNTIL
llama3:70b  bcfb190ca3a7  42 GB   100% GPU    4 minutes from now

On Windows run the same command in PowerShell. Later in this guide the same command shows the context size (the CONTEXT column) so you can check the number you set.

Step 2: Install Aider#

Aider's documented first choice is the small aider-install helper. It installs Aider in its own environment and installs Python 3.12 if your system does not have it.

Linux#

python3 -m pip install aider-install
aider-install

Windows (PowerShell)#

python -m pip install aider-install
aider-install

Mac (Terminal)#

Same commands as Linux:

python3 -m pip install aider-install
aider-install

Check it worked. Close the terminal, open a new one and run:

aider --version

The installer updates your PATH, so a new terminal is needed. If aider is still not found, the docs give one fallback: python -m aider (or python3 -m aider on Linux and Mac). That only works when Aider was installed into the Python you are calling, so it is a fallback, not a replacement for the new terminal.

Tip: If aider is not found on Windows, do not reinstall. Open a new PowerShell window first. Aider's "Aider not found" page says the problem "often happens to Windows users" because of permission and security settings, so a new window is the first thing to try.

Step 3: Start Ollama with a larger context window#

This is the step that most often goes wrong. Ollama's own FAQ says the default context is 4096 tokens. Aider's Ollama page still says 2k. Either way the default is small, and Ollama drops whatever does not fit without telling you. Ollama's context page advises at least 64000 tokens for coding tools. The steps below use 65536, which meets that advice; use 8192 (the Aider docs' example) on a small machine.

Linux#

Run Ollama in a terminal with the variable set:

OLLAMA_CONTEXT_LENGTH=65536 ollama serve

If Ollama runs as a systemd service, Ollama's FAQ sets the variable in a service override instead: sudo systemctl edit ollama.service, add Environment="OLLAMA_CONTEXT_LENGTH=65536" under [Service], then run sudo systemctl daemon-reload and sudo systemctl restart ollama.

Windows (PowerShell)#

setx sets a user variable for new programs, the same way the Aider docs set OLLAMA_API_BASE. Then restart Ollama from the tray, because it reads the variable at start-up.

setx OLLAMA_CONTEXT_LENGTH 65536

Quit Ollama from the tray icon and start it again from the Start menu.

Mac (Terminal)#

The Mac app does not read variables from your shell, so set it for the app with launchctl, as Ollama's FAQ describes:

launchctl setenv OLLAMA_CONTEXT_LENGTH 65536

Then quit the Ollama app and open it again.

Check it worked. You confirm this in Step 4, when a model is loaded: ollama ps shows the CONTEXT column with the number you set (the docs show a value of 131072 for a model on a large GPU; yours will match the number you set, if the model fits).

Tip: Ollama's context page says a larger context needs more memory, and more than one parallel request multiplies it. If the model slows down or moves to the CPU, lower the number. Check the PROCESSOR column in ollama ps.

Step 4: Pull a model and connect Aider to it#

Pick a model from the Ollama library that fits your memory. Aider's docs do not name a model size; they ask you to pick a capable one.

Linux#

ollama pull <model>
cd /path/to/your/project
aider --model ollama_chat/<model>

Windows (PowerShell)#

ollama pull <model>
cd C:\path\to\your\project
aider --model ollama_chat/<model>

Mac (Terminal)#

Same commands as Linux:

ollama pull <model>
cd /path/to/your/project
aider --model ollama_chat/<model>

Use the ollama_chat/ prefix: Aider's Ollama page recommends it over ollama/. Aider reads OLLAMA_API_BASE; the docs give http://127.0.0.1:11434 as the usual value, so you normally do not need to set it.

Check it worked. Send one short message in the chat. Then, in another terminal, run ollama ps. The CONTEXT column should show your number. Aider's start-up lines look like this; this output is quoted from GitHub issue #4798 (aider v0.86.1, a different model name), so it shows the format, not your setup:

Aider v0.86.1
Model: ollama/phi3.5:3.8b-mini-instruct-q4_K_M with whole edit format

Step 5: Set the context per model with a settings file#

Step 3 sets the size for Ollama as a whole. Aider can also ask for a size per model, which is what its docs recommend when you want a fixed value for one model. Create .aider.model.settings.yml in the project folder, with the model name written exactly as you pass it to --model.

Linux#

cat > .aider.model.settings.yml <<'EOF'
- name: ollama_chat/<model>
  extra_params:
    num_ctx: 65536
EOF
aider --model ollama_chat/<model> --model-settings-file .aider.model.settings.yml

Windows (PowerShell)#

Set-Content -Path .aider.model.settings.yml -Value @'
- name: ollama_chat/<model>
  extra_params:
    num_ctx: 65536
'@
aider --model ollama_chat/<model> --model-settings-file .aider.model.settings.yml

Mac (Terminal)#

Same commands as Linux:

cat > .aider.model.settings.yml <<'EOF'
- name: ollama_chat/<model>
  extra_params:
    num_ctx: 65536
EOF
aider --model ollama_chat/<model> --model-settings-file .aider.model.settings.yml

Check it worked. After one message, ollama ps shows the CONTEXT value for your model. If it still shows the Ollama default, the name in the file and the name you passed to --model do not match exactly. That mismatch is the cause of GitHub issue #4798, described in Troubleshooting.

Step 6: Make one small change and read the git log#

Let Aider change one file, so you see what it does to your repository.

Linux#

In the Aider chat, add one file and ask for one small edit:

/add src/main.py
Add a docstring to the main function. Change nothing else.

After Aider applies the edit, in a second terminal:

git log --oneline -3

Windows (PowerShell)#

Same chat commands as Linux. Then in PowerShell:

git log --oneline -3

Mac (Terminal)#

Same commands as Linux:

git log --oneline -3

Check it worked. The newest commit is Aider's. Aider's docs say it marks its commits: when Aider wrote the change, "(aider)" is added to the git author name. Use git show --stat HEAD to see which files it changed. Use /undo in the chat to take the change back.

Git auto-commits: what they do to your repo#

Aider's git integration is the reason to use it in a repo, and also the part that changes your history. These are the rules from the git page of the docs.

• Each edit is a commit. "Whenever aider edits a file, it commits those changes with a descriptive commit message."
• Your pending changes are committed first. "Aider will first commit any preexisting changes with a descriptive commit message." Your half-finished work becomes its own commit before Aider edits anything. Commit or stash your work before you start, so the history stays clean.
• Messages follow Conventional Commits by default. The commit message is written by a second, smaller model (the weak model), not the one you chat with.
• Attribution. Aider appends "(aider)" to the author and committer name. A Co-authored-by trailer is added by default. You can turn these off with --no-attribute-author, --no-attribute-committer or --no-attribute-co-authored-by.
• Pre-commit hooks are skipped. "By default, aider skips pre-commit hooks by using the --no-verify flag." Your secret scanner or linter hook will not run on Aider's commits unless you add --git-commit-verify. Open issue #5376 (July 2026) calls this a silent bypass.
• Undo. /undo reverts and discards the last change. /diff shows what changed since your last message. /git runs raw git commands.
• Switches. --no-auto-commits, --no-dirty-commits and --no-git turn these behaviours off; the docs say --no-git is not recommended.

Tip: Run git status before every Aider session. If the list is not empty and you do not want it in the history, commit or stash first. Aider will commit it for you otherwise.

Privacy: what leaves your machine#

Aider has two parts that can talk to the network: the model connection and its own housekeeping. With a local Ollama model, the model connection stays on your computer.

The docs do not promise that Aider runs with no network at all; test that on your own network.

Security and testing#

• Keep Ollama local. It binds to 127.0.0.1:11434 by default (Ollama FAQ). Changing OLLAMA_HOST to 0.0.0.0 exposes it to your network. Do not put it on the public internet.
• Secrets. A local Ollama setup needs no API key. Cloud providers take keys from the environment or a .env file (Aider's .env page lists the names). Keep .env out of git: add it to .gitignore. On Linux and Mac you can restrict it with chmod 600 .env.
• Functional test. This sends one message and exits, so you can test the connection without the chat:

aider --model ollama_chat/<model> --message "Reply with the word ready." --no-git

aider --model ollama_chat/<model> --message "Reply with the word ready." --no-git

Check it worked. Aider prints the model's reply and exits. If it hangs, look at ollama ps and at the Ollama terminal or log. --no-git is used here only so the test does not write a commit.

Common mistakes#

Each row is taken from the Aider docs or from a real issue in the Aider tracker (state and date as read in October 2026). The last row is about AI assistants.

Tip: Make the first session a throwaway: a small repo, a clean git status, one /add.

Tip: Run ollama ps in a second terminal while you work. The CONTEXT and PROCESSOR columns tell you the two things that most often break a local setup: the size you set, and whether the model is running on the GPU or the CPU.

Tip: Use --map-tokens 0 to turn off the repository map if the model is slow and you do not need Aider to read the whole project (options reference: "use 0 to disable").

Troubleshooting#

Exact error texts#

aider: The term 'aider' is not recognized as a name of a cmdlet, function, script file, or executable program. This is the Windows PowerShell message quoted on Aider's "Aider not found" page. Open a new window, or use python -m aider.

litellm.APIConnectionError: Unable to parse ollama chunk is the title of issue #4594 (open since October 2025), reported on Windows 11 with an Ollama cloud model. It is not a general fix: check that the model runs in ollama ps, then test with a local model to tell the two apart.

ModuleNotFoundError from pydub's import audioop on Python 3.13 is the failure in issue #3660. Install Python 3.12 through aider-install.

Known bugs (open on October 30, 2026)#

• #5874 (October 2026): /undo does not send its reply to models that need send_undo_reply, so the model may not learn that its change was reverted.
• #5620 (August 2026): a path outside the repo crashes the session in is_dirty().
• #5376 (July 2026): pre-commit hooks are skipped by default.
• #4764 (January 2026): Ollama reloads with large contexts; the reporter says the reload often takes longer than the answer.
• #3891 (April 2025): commit fails when the tree is dirty.
• #3037 (April 2025): Python 3.13 is not supported.

Updates and backups#

Update. Aider's options reference lists --upgrade, which upgrades Aider from PyPI:

aider --upgrade

aider --upgrade

Ollama updates separately: on Mac and Windows it updates itself, on Linux re-run the install script (Ollama FAQ).

Back up your work. Aider is not a server and has no Docker volume, so there is no ~/docker_volumes folder for it. Your data is your repo and its history. A git bundle is a single file with the whole history, and it needs nothing extra. On Linux and Mac:

mkdir -p ~/backups
git bundle create ~/backups/my-project-$(date +%F).bundle --all

On Windows PowerShell:

New-Item -ItemType Directory -Force $HOME\backups | Out-Null
git bundle create "$HOME\backups\my-project-$(Get-Date -Format yyyy-MM-dd).bundle" --all

Schedule it with cron at 03:00 on Linux and Mac, or with Windows Task Scheduler. Leave model files out: Ollama can download them again.

Restore test. Make a folder and clone from the bundle, then check the history:

git clone ~/backups/my-project-<date>.bundle restore-test
cd restore-test && git log --oneline -3

If the commits are there, the bundle works.

Performance and resources#

• Context memory. The bigger the context, the more memory Ollama uses. Ollama's FAQ says RAM scales with OLLAMA_NUM_PARALLEL times OLLAMA_CONTEXT_LENGTH.
• VRAM defaults. Ollama's context page sets the default by GPU memory: under 24 GiB, 4k; 24 to 48 GiB, 32k; 48 GiB or more, 256k. Coding tools should be set to at least 64000 tokens.
• The repo map. Aider sends a map of your repo to the model. --map-tokens N sets its size, and 0 turns it off. Lower it when the model is slow.
• Monitoring. ollama ps shows the model's processor split (100% GPU, 100% CPU, or a mix) and the CONTEXT size. Watch it while Aider works.
• No figures here. Aider's docs publish no RAM or speed numbers for local models, and we took no timings.

FAQ#

Does it work without an internet connection? The docs do not promise it. With a local Ollama model the prompts stay on your machine, and you can turn off the update check and analytics. Test it on your own network before you rely on it.

Which model should I use? Aider's docs say that most local models are only just capable of editing code, and that weaker models disobey the system prompt more often. Check the Aider leaderboards, pick the largest coder model your memory can hold, and keep the CONTEXT setting in mind.

Do I need a GPU? Aider does not say. Ollama runs models on the CPU as well, and ollama ps shows the split. A CPU-only machine works but is slower.

Is Aider still maintained? Yes, with a caveat. The issue tracker is active (issues were opened in October 2026), but the newest PyPI release is from February 2026 and the last commit on the main branch is from May 2026. Plan for slower releases.

Sources#

• Aider documentation - read October 2026
• Aider installation and aider-install on PyPI (its README on GitHub) - read October 2026
• Aider with Ollama - read October 2026
• Aider git integration - read October 2026
• Aider options reference and YAML config file - read October 2026
• Aider analytics - read October 2026
• Aider not found and edit errors - read October 2026
• aider-chat on PyPI (0.86.2) and Aider on GitHub (Apache 2.0) - read October 2026
• Ollama FAQ and Ollama context length - read October 2026
• GitHub issues in Aider-AI/aider: #4764, #4798, #4583, #5376, #5874, #5620, #3891, #3037, #3660, #3123, #3974, #4594 - read October 2026

Checked against the official docs on 2026-10-30.