You’re right — this is almost always caused by tool version or environment drift
between local setup and CI.

🔧 How to align local checks with CI

1. Pin to the repo’s pre-commit tool versions

   • Check .pre-commit-config.yaml for the exact rev values (ruff, mypy, etc.).
   • Then run:

     pre-commit clean
     pre-commit run --all-files

   This ensures your local hooks use the same versions CI uses.

2. Match the Python version used in CI

   • Check the GitHub Actions workflow for the Python version matrix.
   • Create your virtual environment with the same Python version.
   • Python version mismatches commonly surface as mypy errors.

3. Install repo-pinned dependencies

   • Prefer any provided requirements.txt or requirements-dev.txt.
   • Avoid installing tools globally (e.g. pip install mypy) unless CI does the same.

4. Treat pre-commit as the source of truth

   • CI usually runs:

     pre-commit run --all-files

   • Running mypy . directly can differ because pre-commit may pass additional flags
     or configuration options.

📁 About errors in files you didn’t modify

• It’s not expected to fix unrelated type issues in the same PR.
• Recommended approach:
  • Keep the PR focused on your change.
  • If you uncover genuine repo-wide issues, open a separate PR or discussion.
  • Limiting checks to staged files is usually discouraged unless the project
    explicitly recommends it.

It looks like you're dealing with a classic cache mismatch or environment drift. Since aayush-dev01 mentioned the version alignment, here is the specific command sequence to force your local environment to exactly match the GitHub Actions state:

Force-update your hooks: Sometimes pre-commit caches an older version of the hook even if the config changes.
Bash

pre-commit autoupdate
pre-commit clean

Run via the environment, not the system: Instead of running mypy ., always run it through pre-commit to ensure the flags in .pre-commit-config.yaml are applied:
Bash

pre-commit run mypy --all-files

The "Shadow" Dependencies: If errors appear in files you didn't touch, it's often because your local venv has a newer (or older) version of a library than the one pinned in the repo's requirements.txt. Re-sync your venv:
Bash

pip install -r requirements.txt --force-reinstall

Regarding the unrelated errors: Definitely do not fix them in your PR. It makes the code review much harder. Keep your PR "atomic" (only your changes). If the errors persist but CI passes, you can safely ignore them as long as your specific changes are clean!

Hope this helps you get that contribution merged! 🚀

The key issue is version drift. Here's how to fix it:

1. Use the exact Python version from CI

Check .github/workflows/ci.yml for the Python version used in CI, then match it locally:

pyenv install 3.12.0   # or whatever CI uses
pyenv local 3.12.0

Or use runtime.txt / .python-version if the repo has one.

2. Install pinned dependencies

The repo's requirements.txt or pyproject.toml has pinned versions. Install them exactly:

python -m pip install -r requirements.txt
pre-commit install

The critical part: run pre-commit hooks using the same versions CI uses. The .pre-commit-config.yaml file at the repo root pins exact hook versions (e.g., rev: v0.6.9 for ruff). Make sure you have the latest hooks:

pre-commit autoupdate
pre-commit run --all-files

3. Pin mypy to the CI version

Don't pip install mypy separately — instead install the version specified in CI. Check .github/workflows/ci.yml for the mypy version, then:

python -m pip install mypy==1.11.0  # match CI version

Or better, use the exact environment from CI:

python -m pip install -e .[dev]  # if dev extras exist

4. Limit checks to staged files only

This is the recommended workflow and avoids being blocked by pre-existing errors:

pre-commit run  # without --all-files → checks only staged changes

Or for mypy specifically:

mypy path/to/your/file.py  # check only the files you changed

5. If you hit pre-existing type errors

Open a separate PR to fix them, or mention in your PR description that the errors are pre-existing and unrelated to your change. Most maintainers prefer focused PRs.

Quick fix checklist

1. python --version matches CI
2. pre-commit --version matches the hook versions in .pre-commit-config.yaml
3. Use pre-commit run (no --all-files) to check only your changes
4. Run mypy only on your files: mypy your_file.py
5. If CI uses uv or poetry, use the same lock file

Discrepancies between local pre-commit hooks and CI arise because local checks often scan only staged files while CI evaluates the full repository, combined with differing environments. To align them, run pre-commit run mypy --all-files locally, clear caches, and define required dependencies in .pre-commit-config.yaml. Detailed community solutions can be found on GitHub and Stack Overflow.