pre-commit / mypy results differ from CI on main — how do I align my local toolchain?

[devilfoo]

I am preparing a small contribution, but I’m seeing mismatches between my local checks and what passes in CI. Locally, pre-commit (ruff + mypy) fails with type‑checking errors in files I did not modify, while the main branch appears clean. I suspect a tool‑version or environment drift between my machine and CI.

Steps to Reproduce

git clone https://github.com/TheAlgorithms/Python
cd Python

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

python -m pip install --upgrade pip
python -m pip install pre-commit
pre-commit install

pre-commit run --all-files --show-diff-on-failure

python -m pip install mypy
mypy .

Actual Result

Mypy reports errors in unrelated modules (e.g., incompatible types) even though the same files appear to pass CI on main.

Question

What is the correct way to align local tool versions (Python, ruff, mypy, pre‑commit hooks) with the versions used in CI so that local checks match CI behavior?

If type errors appear outside the files I changed, is it recommended to limit checks to staged files or open a separate PR to address repository‑wide issues?

[Avik-Das-567]

You’re exactly right that this is almost always toolchain drift rather than “new” errors.

1. How to align your local environment with CI

The key rule for TheAlgorithms/Python is: CI is the source of truth. Your local setup should mirror CI, not the other way around.

Use the repo-pinned versions (not global installs)

Do not install mypy, ruff, or black manually. CI runs the versions pinned in .pre-commit-config.yaml.

Instead, do this:

git clone https://github.com/TheAlgorithms/Python
cd Python

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

python -m pip install --upgrade pip pre-commit
pre-commit install

# IMPORTANT: sync hook versions exactly
pre-commit autoupdate
pre-commit run --all-files

Then check what CI is using:

• .pre-commit-config.yaml → exact ruff, mypy, formatter versions

• .github/workflows/*.yml → Python version used in CI (often 3.10 or 3.11)

  If your local Python version differs from CI, that alone can change mypy results.

Best practice: match CI’s Python version exactly.

python --version

If needed, recreate your venv with the correct Python.

2. Why you’re seeing mypy errors in untouched files

This is expected behavior.

• pre-commit run --all-files and mypy . check the entire repository

• CI may:

  • Use a narrower path
  • Suppress known issues
  • Or rely on cached baseline behavior

So your local run can legitimately surface pre-existing type issues.

3. Should you limit checks or fix unrelated errors?

Recommended approach (and what maintainers prefer):

For your contribution:

• Run full pre-commit locally
• Fix issues only if they are in files you touched
• Do not mix unrelated fixes into your PR

What not to do:

• Don’t disable hooks
• Don’t downgrade mypy locally
• Don’t bundle repo-wide cleanup with a small change

If you want to help further:
Open a separate PR clearly titled, for example:

“Fix mypy errors in (unrelated cleanup)”

Maintainers are much more likely to accept it that way.

TL;DR

• CI versions come from .pre-commit-config.yaml
• Match Python version + pre-commit hooks
• Don’t manually install mypy/ruff
• Ignore unrelated errors unless you want a separate cleanup PR

If your local checks match pre-commit run --all-files with the pinned versions, you’re doing it right; even if CI currently passes with known debt.

You’re on the right track.