Troubleshooting guide

Solutions for common mypy problems and debugging techniques

This guide helps you diagnose and fix common problems when using mypy.

Installation issues

Mypy not found after installation

If mypy command is not found:

1. Check installation

   python3 -m mypy --version
   
2. Verify PATH

   Ensure pip’s bin directory is in your PATH:

   python3 -m pip show mypy
   
3. Use python -m

   Always run as module if command not found:

   python3 -m mypy myproject
   

Version conflicts

# Check installed version
python3 -m mypy --version

# Install specific version
python3 -m pip install mypy==1.8.0

# Upgrade to latest
python3 -m pip install --upgrade mypy

Module and import issues

Cannot find implementation or library stub

error: Cannot find implementation or library stub for module named 'foo'

Solution 1: Install the package

The module might not be installed:

pip install foo

Solution 2: Install stub package

Install type stubs:

pip install types-foo
# Or use mypy's helper:
mypy --install-types

Solution 3: Ignore missing imports

Add to mypy.ini:

[mypy-foo.*]
ignore_missing_imports = True

Solution 4: Create stub file

Create a minimal stub:

# stubs/foo.pyi
def bar(x: int) -> str: ...

Then:

export MYPYPATH=./stubs

Module not found in MYPYPATH

Verify MYPYPATH is set correctly:

echo $MYPYPATH
export MYPYPATH=/path/to/stubs:$MYPYPATH

Namespace package issues

For namespace packages without __init__.py:

mypy --namespace-packages mypackage

Or in configuration:

[mypy]
namespace_packages = True

Configuration issues

Config file not found

Mypy searches for config files in this order:

1. mypy.ini
2. .mypy.ini
3. pyproject.toml
4. setup.cfg

Specify explicitly:

mypy --config-file custom-mypy.ini myproject

Config options not working

Verify the config is being read:

mypy --verbose myproject | grep "mypy.ini"

Check for syntax errors in config file:

# Wrong - don't use quotes
[mypy]
python_version = "3.10"

# Correct
[mypy]
python_version = 3.10

Per-module config not applying

Module patterns must match import names:

# Wrong - using file paths
[mypy-src/myproject/utils.py]

# Correct - using module names
[mypy-myproject.utils]

Cache issues

Stale cache causing errors

Clear the cache:

rm -rf .mypy_cache
mypy myproject

Or disable caching temporarily:

mypy --no-incremental myproject

Cache permission errors

# Fix permissions
chmod -R u+w .mypy_cache

# Or use different cache location
mypy --cache-dir=/tmp/mypy_cache myproject

Type checking issues

False positives

Mypy reports errors that seem incorrect:

Use reveal_type

Debug what mypy thinks:

reveal_type(x)  # Shows what mypy infers

Check for Any

Any can hide issues:

mypy --disallow-any-unimported --disallow-any-expr myproject

Update stubs

Stubs may be outdated:

pip install --upgrade types-requests

False negatives

Mypy doesn’t catch obvious errors:

1. Missing annotations: Add type hints to functions
2. Any leakage: Check for implicit Any types
3. Ignored files: Verify files are being checked

mypy --warn-return-any --warn-unused-ignores myproject

Performance issues

Slow initial run

For large codebases:

1. Use daemon mode

   dmypy start
   dmypy run -- myproject
   
2. Enable incremental mode

   [mypy]
   incremental = True
   
3. Exclude unnecessary files

   [mypy]
   exclude = (?x)(
       ^tests/
       | ^build/
       | ^venv/
   )
   

Slow incremental runs

# Skip version check
mypy --skip-version-check myproject

# Skip cache mtime checks
mypy --skip-cache-mtime-checks myproject

Memory issues

# Reduce memory usage
export MYPYC_OPT_LEVEL=0
mypy --no-incremental myproject

Daemon mode (dmypy) issues

Daemon won’t start

Check if already running:

dmypy status
dmypy stop
dmypy start

Daemon returns stale results

Restart the daemon:

dmypy restart

Or force recheck:

dmypy recheck

Socket errors

# Kill daemon and remove socket
dmypy kill
rm -f .dmypy.json
dmypy start

Platform-specific issues

Windows path issues

# Use forward slashes or double backslashes
mypy myproject/main.py
mypy myproject\\main.py

macOS compilation issues

If mypyc compilation fails:

# Install Xcode Command Line Tools
xcode-select --install

# Or use interpreted version
pip install --no-binary mypy mypy

Debugging techniques

Enable verbose output

mypy --verbose myproject

This shows:

• Which files are being checked
• Which config file is being used
• Import resolution details

Show traceback for crashes

mypy --pdb --show-traceback myproject

Export type information

# Generate HTML report
mypy --html-report report myproject

# Generate text report
mypy --txt-report report myproject

Use reveal_type and reveal_locals

def debug_function(x, y):
    reveal_type(x)  # Shows type of x
    z = x + y
    reveal_locals()  # Shows all local types
    return z

CI/CD issues

Mypy fails in CI but passes locally

Check Python version

Ensure CI uses same Python version:

- uses: actions/setup-python@v4
  with:
    python-version: '3.10'  # Match local version

Check mypy version

Pin mypy version:

- run: pip install mypy==1.8.0

Check dependencies

Install all dependencies:

- run: pip install -r requirements.txt

Clear cache in CI

Don’t cache mypy cache:

- run: rm -rf .mypy_cache && mypy myproject

Common error patterns

Assignment errors

# Error: Incompatible types in assignment
x: int = "hello"

# Fix: Use correct type
x: str = "hello"
# Or: Change value
x: int = 42

Call errors

# Error: Too many arguments
def greet(name: str) -> None:
    print(name)

greet("Alice", "Bob")  # Error

# Fix: Match function signature
greet("Alice")

Import errors

# Error: Cannot find module
import nonexistent

# Fix: Install or ignore
# pip install nonexistent
# Or add to mypy.ini:
# [mypy-nonexistent.*]
# ignore_missing_imports = True

Getting help

If you’re still stuck:

Check documentation

Review the full documentation

Search issues

Search existing GitHub issues

Ask on Gitter

Join the typing discussion

Report a bug

File a new issue

When reporting issues, include:

• Mypy version (mypy --version)
• Python version
• Minimal reproduction example
• Config file content
• Complete error message