# Gemini CLI for Python projects: a practical guide

URL: https://agentvera.dev/en/blog/gemini-cli-for-python/ · Published: 2026-11-01

Use Gemini CLI on Python projects with a clear GEMINI.md, virtualenv, pytest, ruff, and mypy. Learn setup, prompt loops, pitfalls, and parallel agents.

**In short:**

- Put Python-specific commands in GEMINI.md: activate the venv, install the package, run pytest, ruff, and mypy.
- Work in small steps: ask Gemini CLI to change one module, run tests, show the diff, and fix only related errors.
- Watch for venv confusion, broad dependency edits, and tests modified to pass; use AgentVera for parallel worktrees and review.

Gemini CLI is Google’s terminal coding agent for working directly in a project. For Python, the practical way to use it is to run `gemini` inside a virtual environment with a `GEMINI.md` that records your exact install, lint, type-check, and test commands. The agent reads that file and uses your real terminal, so it can act on pytest, ruff, and mypy feedback instead of guessing.

## Where Gemini CLI earns its keep in Python codebases

Python has fast feedback loops: you change a module, run pytest, run ruff, run mypy, and read specific tracebacks. Gemini CLI is useful when those loops are explicit. It can open your code, make a narrow edit, run the command you named, read the error, and iterate. That matches Python’s style of small modules, explicit imports, and tests that should fail for one reason at a time. Typed Python makes the loop even stronger because mypy output often names the exact file and line the agent needs to revisit. The agent is not a replacement for good project layout; it is a force multiplier when your `pyproject.toml` already declares deterministic commands.

## Making the project agent-ready with GEMINI.md

Before starting `gemini`, create the virtual environment and install the project in editable mode. The agent does not manage your environment magically; it runs commands in the current terminal. A clean setup prevents most Python-specific failures.

The most important file is `GEMINI.md` at the repo root. Keep it concrete and short. For a Python project, it should state the Python version, the venv activation command, how to install, and the exact commands for testing, linting, and type checking. It should also state folder conventions and rules such as “do not edit `pyproject.toml` without approval” and “run pytest, ruff, and mypy after each change.” Here is a realistic example:

```markdown
# Project instructions for Gemini CLI

Python 3.12. Activate the existing venv with:
source .venv/bin/activate

Install the package and dev tools:
pip install -e ".[dev]"

Run tests:
pytest -q

Lint and format checks:
ruff check .

Type check:
mypy src

Layout:
- src/mypkg/ contains application code
- tests/ mirrors src/mypkg/ one-to-one
- scripts/ is for one-off utilities

Rules:
- Keep changes small and scoped to one module or behavior.
- Use `from __future__ import annotations`; do not introduce `Any` without a comment.
- Prefer explicit `-> None` on functions that return nothing.
- After every change, run pytest, ruff, and mypy. Fix only errors related to the change.
- Do not modify pyproject.toml, CI files, or lockfiles unless explicitly asked.
- When a test fails, read the full traceback before editing; do not weaken assertions to make a test pass.
```

This file turns the agent from a general assistant into a project-specific Python pair. The key files the agent will touch have clear roles:

| File | Purpose |
|---|---|
| `GEMINI.md` | Defines commands and constraints for every agent turn |
| `pyproject.toml` | Declares dependencies, package config, and tool settings |
| `src/mypkg/` | Source code the agent should edit |
| `tests/` | pytest tests that protect the source behavior |

## A day-to-day edit-test-review loop

Use a plan, small step, test, review loop. Ask for one behavior at a time, require the verification commands from `GEMINI.md`, and read the diff before accepting. This is close to [AI pair programming: how to work with a coding agent](/en/blog/ai-pair-programming/), but the Python version is stricter: if the venv is not active, commands fail; if tests are not run, a type fix can silently break imports.

Example prompts for typical Python tasks:

- “Add a frozen dataclass `User` in `src/mypkg/models.py` with fields `id: int`, `email: str`, and `is_active: bool = True`. Add a `to_dict` method and a matching pytest test in `tests/test_models.py`.”
- “Write pytest tests for `validate_email` in `src/mypkg/validation.py` using `pytest.mark.parametrize`. Cover an empty string, a missing `@`, and a valid address.”
- “Refactor `load_config` to return a `Config` TypedDict instead of a plain dict. Update call sites in `src/mypkg` and add type coverage in `mypy`.”
- “Run `pytest -q`, `ruff check .`, and `mypy src`. Fix only the failures introduced by the previous change, then rerun all three.”
- “Explain the failing test traceback for `test_parse_iso`, propose the smallest fix, show it as a diff, and wait for approval.”

Keep each turn small enough that you can review the entire diff in a few minutes. If the agent says it cannot run a command, check that the venv is active in your terminal and that the editable install completed.

## What Gemini CLI does well in Python and where to be careful

Gemini CLI is good at adding type hints, generating pytest cases from a function signature, refactoring a module into smaller modules, updating imports after a rename, and converting a function to async when the surrounding code already follows a clear pattern. It can also write the boilerplate for a dataclass, Pydantic model, or CLI entry point when your `pyproject.toml` already has the dependencies.

Watch it closely in areas that are error-prone in Python. The most common issue is environment confusion: the agent may run a command with the system Python instead of the venv if the activation line is missing from `GEMINI.md` or the shell session was reopened. Another pitfall is broad dependency edits: adding or upgrading packages without checking the lockfile or Python version constraints. It may also use `Any` too freely, add `# type: ignore` to silence mypy, or change a test assertion to make a failing test pass. Review any changes to `tests/` with suspicion, and require a separate test run before accepting a “fix.”

The agent may also overlook the difference between runtime and import-time side effects, especially in `__init__.py`. For a Python project, a helpful rule is to ask the agent to explain why a change belongs in a particular module before editing.

## Using tests and types as acceptance gates

Do not accept an agent turn without a green verification command. The minimum bar for Python work is: `pytest -q`, `ruff check .`, and `mypy src`. Have the agent run all three after every change, and paste the output into the conversation when something fails. For new behavior, require a test before the implementation is considered complete. This makes the agent work like a test-driven loop: it writes or updates a test, sees it fail, edits the source, and reruns the test.

Use `git diff` to review exactly what changed. For tricky tracebacks, follow a similar workflow to [How to debug code with AI: a practical workflow](/en/blog/debug-code-with-ai/): ask for the root cause first, then a minimal patch, then the verification commands. If the agent changes a type, confirm mypy passes on the source directory; if it touches packaging, confirm the editable install still works in the venv.

## Coordinating several agents with AgentVera

When one Python change touches several areas, you can run multiple Gemini CLI sessions side by side with AgentVera. It runs the real command line tools in separate terminal panels, so each agent can work in its own git worktree and avoid overwriting files. After a turn ends, a second model reviews the code and links findings to exact lines, which helps catch type errors, weak tests, or venv issues. Token budgets keep a long refactor from running away while preserving the conversation after the cap. This is useful for Python worktrees because you can keep a baseline branch intact while agents try independent edits.

## Bottom line

Gemini CLI works best on a Python project when the project tells the agent exactly how to verify work. Write a short `GEMINI.md` with your venv activation, editable install, pytest, ruff, and mypy commands, then use a small review loop. For larger efforts, parallel worktrees and automatic review help keep the codebase clean. If you are new to Gemini CLI itself, start with the [Gemini CLI overview](/en/agents/gemini-cli/) or the [step-by-step guide](/en/blog/how-to-use-gemini-cli/).

## Frequently asked questions

**How do I start Gemini CLI on a Python project?** Open the project folder, activate your virtual environment, and run gemini in the terminal. Put the venv activation and verification commands in GEMINI.md so the agent uses the same environment.

**What should I include in GEMINI.md for Python?** Include the Python version, venv activation, editable install, pytest, ruff, and mypy commands, the source and test layout, and rules such as not editing pyproject.toml without approval.

**Can Gemini CLI run pytest and fix failing tests?** Yes. It can run pytest -q, read the traceback, propose a minimal fix, and rerun the test. Ask it to show a diff before applying a change and never weaken assertions.

**Does Gemini CLI work with virtual environments?** Yes, but it does not create or manage them automatically. Create the venv yourself and record the activation command in GEMINI.md, or the agent may use the wrong Python interpreter.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/