Aider on Python projects using Poetry: dependency management awareness

Published 2025-12-27 by Owner

Poetry remains a popular Python package manager. Aider works on Poetry projects fine, but a few configurations make the experience smoother.

The basics work

Aider doesn’t need special config for Poetry. It reads Python files, edits them, commits via git. Poetry-specific files (pyproject.toml, poetry.lock) are just files to aider.

For most work, the defaults are fine.

Where Poetry-specific awareness helps

A few places where helping aider understand Poetry produces better results:

Adding dependencies. When aider needs a new package, it might suggest pip install rather than poetry add. Add to .aider.conf.yml:

read:
  - CONVENTIONS.md

Where CONVENTIONS.md says:

This project uses Poetry. To add dependencies, suggest `poetry add <package>`,
not `pip install`. To run scripts, use `poetry run <script>`. To install
the project for development, use `poetry install`.

After this, aider’s suggestions about dependencies match the project.

Lock file awareness. When pyproject.toml changes, poetry.lock should be regenerated. Aider doesn’t do this automatically. Add a reminder in CONVENTIONS.md:

After modifying pyproject.toml dependencies, run `poetry lock` to update
the lock file. Do not modify poetry.lock directly.

Virtualenv handling. Poetry creates a virtualenv. Tests run inside it. The auto-test config:

auto-test: true
test-cmd: poetry run pytest

The poetry run prefix ensures the venv is active. Without it, tests may run against the wrong environment.

A specific failure mode

A pattern I’ve seen:

User asks aider to add an HTTP client. Aider:

Adds import httpx to a Python file
Runs the test suite
Tests fail with ModuleNotFoundError: No module named 'httpx'
Aider tries to “fix” by adding import requests (a different library)
Tests fail differently

The actual fix is poetry add httpx. Aider’s training tends toward “modify code to fit the environment” rather than “modify the environment to fit the code.”

After CONVENTIONS.md mentions Poetry: aider correctly suggests poetry add httpx and the user runs it.

Per-project virtualenv

If your project has the venv inside the project directory (poetry’s in-project mode):

# poetry.toml
[virtualenvs]
in-project = true

The venv ends up at .venv/ inside the project. Add to .aiderignore:

.venv/

Without this, aider’s repo map includes the entire venv (huge token waste).

Pre-commit hooks

If you use Poetry’s pre-commit integration:

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: ruff
      entry: poetry run ruff check
      language: system

Aider’s auto-commit triggers these. The pre-commit feedback loop works.

For complex pre-commit setups, see the separate guide on Aider + pre-commit hooks.

The dev dependencies

Poetry distinguishes main dependencies from dev dependencies. Aider’s suggestions don’t always know which group a dependency belongs in.

For test-only dependencies:

poetry add --group dev pytest

For runtime dependencies:

poetry add httpx

If aider suggests adding pytest as a main dependency, correct it. Mention in CONVENTIONS.md if this happens often.

What I’d skip

A few things I don’t bother with:

Poetry-specific aider plugins. None exist. Standard aider works.

Custom aider commands for Poetry workflows. Just use Poetry’s commands directly. No need to wrap in aider.

Specialized models for Poetry. No model has special Poetry training. Standard Claude or GPT-4 works fine.

When to migrate from Poetry

Some teams are migrating from Poetry to uv. uv is faster, simpler, more modern.

For aider users specifically: uv is even smoother. Aider’s defaults work with uv without configuration. Poetry requires the small config above; uv mostly doesn’t.

If you’re starting a new Python project: consider uv over Poetry. If you’re on Poetry and it works: don’t migrate just for aider; the gain is bounded.

Summary

Poetry + aider works with minimal config. The CONVENTIONS.md additions and .aiderignore exclusion address the main friction points. Once configured, aider on Poetry projects is roughly as smooth as on any other Python project.

For most users, this is 10 minutes of setup that pays off across the project’s lifetime.