Mypy Linter for Python LSP Server

Common errors

• Cannot find implementation or library stub for module named "module name"

  cause Mypy cannot find a module imported in your code, often a local custom module or a third-party library whose stubs are not properly installed/detected. This can be due to an incorrect Python environment or `mypy_path` configuration.
  fix Ensure `mypy` is running in the correct virtual environment with all project dependencies installed. Verify that your `pyproject.toml` (or `mypy.ini`) correctly specifies `mypy_path` if you have custom source directories not at the project root. For third-party libraries, ensure type stubs are installed (e.g., `pip install types-yourlibrary`).

• Client X quit with exit code 1 and signal 0 (or Python LSP server not running)

  cause The `python-lsp-server` (which hosts `pylsp-mypy`) failed to start. This often happens after Python interpreter updates, virtual environment corruption, or missing core dependencies for `python-lsp-server` itself.
  fix Reinstall `python-lsp-server`, `pylsp-mypy`, and `mypy` in a clean virtual environment: `pip uninstall -y pylsp-mypy python-lsp-server mypy && pip install python-lsp-server pylsp-mypy mypy`. Verify that the base `python-lsp-server` works before diagnosing `pylsp-mypy` specific issues.

• ERROR Missing dependencies: setuptools>=40.8.0 validate-pyproject -> fastjsonschema<=3,>=2.16.2

  cause A dependency conflict, typically an older version of `fastjsonschema` is installed or a local `pip install` interfered with system packages. `pylsp-mypy` relies on `validate-pyproject` which has a dependency on `fastjsonschema`.
  fix Explicitly install or upgrade `fastjsonschema` to a compatible version: `pip install "fastjsonschema>=2.16.2"`. Consider recreating your virtual environment to resolve potential conflicts.

Warnings

• breaking Python 3.10 is now the minimum required Python version.
  Fix: Ensure your development environment and `python-lsp-server` run on Python 3.10 or newer. If you are on an older Python version, you must use an earlier `pylsp-mypy` version (e.g., 0.6.x supports Python 3.8+).
• gotcha Enabling `dmypy` (daemon mode) currently disables `live_mode`.
  Fix: If you want real-time type checking as you type, keep `dmypy = false` (the default) and `live_mode = true`. If you prioritize faster checks on save for large projects, set `dmypy = true` and accept that `live_mode` will be implicitly disabled.
• gotcha Default `--follow-imports silent` can invalidate `mypy`'s cache.
  Fix: The default `pylsp-mypy` invocation of `mypy` uses `--follow-imports silent`. If you run `mypy` from the command line with its default `--follow-imports normal`, this mismatch will cause `mypy`'s cache to be invalidated, slowing down subsequent runs. To prevent this, either configure `[tool.pylsp-mypy] overrides = [true, '--follow-imports', 'normal']` or set `[tool.mypy] follow_imports = 'silent'` in your `pyproject.toml`.
• gotcha Using `mypy_command` or `dmypy_command` requires an explicit environment variable for security reasons.
  Fix: If you customize the `mypy_command` or `dmypy_command` to run `mypy` from a specific virtual environment or using a wrapper (e.g., `poetry run mypy`), you must set the environment variable `PYLSP_MYPY_ALLOW_DANGEROUS_CODE_EXECUTION`. This is a security measure to prevent arbitrary code execution from potentially malicious project configurations.

Install

• pip install pylsp-mypy Install pylsp-mypy

Imports

• pylsp-mypy

  This library is a plugin and is not typically imported directly in user code. It is loaded and configured by the Python LSP Server.

  pylsp-mypy functions as an extension to the Python LSP Server. Its features are enabled and configured via the LSP client's settings or a `pyproject.toml` file, rather than direct Python imports.

Quickstart

To use `pylsp-mypy`, install it alongside `python-lsp-server` and `mypy` in your development environment. Configuration is typically done via a `[tool.pylsp-mypy]` section in your `pyproject.toml` file, where you can enable it, set `live_mode` for as-you-type checks, and enable `strict` Mypy rules.

# 1. Install pylsp-mypy (and python-lsp-server) in your project's virtual environment:
pip install python-lsp-server pylsp-mypy mypy

# 2. Add or update your pyproject.toml to enable and configure pylsp-mypy:
# (This example enables live mode and strict checking)
# [tool.pylsp-mypy]
# enabled = true
# live_mode = true
# strict = true
# exclude = ["tests/*"]

# 3. Open a Python file in your LSP-compatible editor (e.g., VS Code, Neovim, Emacs)
# The LSP server will automatically detect and load pylsp-mypy for type checking.