Mypy extension for Visual Studio Code

A Visual Studio Code extension with support for the Mypy type checker. This extension ships with mypy=1.15.0.

Note: The minimum version of Mypy this extension supports is 1.15.0. If you have any issues with Mypy, please report it to this issue tracker as this extension is just a wrapper around Mypy.

This extension supports all actively supported versions of the Python language.

For more information on Mypy, see https://www.mypy-lang.org/

Usage and Features

The Mypy extension provides a series of features to help your productivity while working with Python code in Visual Studio Code. Check out the Settings section for more details on how to customize the extension.

Integrated type checking: Once this extension is installed in Visual Studio Code, Mypy will be automatically executed when you open a Python file, reporting any errors or warnings in the "Problems" window.
Customizable Mypy version: By default, this extension uses the version of Mypy that is shipped with the extension. However, you can configure it to use a different binary installed in your environment through the mypy-type-checker.importStrategy setting, or set it to a custom Mypy executable through the mypy-type-checker.path settings.
Per-project environments: In a monorepo, enable mypy-type-checker.usePerProjectEnvironments to use the selected Python environment for each project configured through python-envs.pythonProjects.
Workspace-wide type checking: By default, this extension will only report errors and warnings for files open in the editor. However, you can configure it to report errors and warnings for the entire workspace through the mypy-type-checker.reportingScope setting.
Mono repo support: If you are working with a mono repo, you can configure the extension to offer type checking for Python files in subfolders of the workspace root folder by setting the mypy-type-checker.cwd setting to ${fileDirname}. You can also set it to ignore/skip type checking for certain files or folder paths by specifying a glob pattern to the mypy-type-checker.ignorePatterns setting.
Customizable linting rules: You can customize the severity of specific Mypy error codes through the mypy-type-checker.severity setting.
Mypy Daemon support: This extension supports the Mypy daemon (dmypy) for faster type checking when the reporting scope is set to the entire workspace. To enable it, set the mypy-type-checker.preferDaemon setting to true.

Disabling Mypy

You can skip type checking with Mypy for specific files or directories by setting the mypy-type-checker.ignorePatterns setting.

If you wish to disable Mypy for your entire workspace or globally, you can disable this extension in Visual Studio Code.

Settings

There are several settings you can configure to customize the behavior of this extension.

Settings	Default	Description
mypy-type-checker.args	`[]`	Arguments passed to Mypy to enable type checking on Python files. Each argument should be provided as a separate string in the array. Example: `"mypy-type-checker.args" = ["--config-file=<file>"]`
mypy-type-checker.cwd	`${workspaceFolder}`	Sets the current working directory used to lint Python files with Mypy. By default, it uses the root directory of the workspace `${workspaceFolder}`. You can set it to `${fileDirname}` to use the parent folder of the file being linted as the working directory for Mypy. You can also set it to `${nearestConfig}` to use the nearest parent/ancestor folder which contains a `mypy.ini`, `.mypy.ini`, `pyproject.toml`, or `setup.cfg` file.
mypy-type-checker.severity	`{ "error": "Error", "note": "Information" }`	Mapping of Mypy's message types to VS Code's diagnostic severity levels as displayed in the Problems window. You can also use it to override specific Mypy error codes. For example: `{ "error": "Error", "note": "Information", "name-defined": "Warning" }`
mypy-type-checker.path	`[]`	Path or command to be used by the extension to type check Python files with Mypy. Accepts an array of a single or multiple strings. If passing a command, each argument should be provided as a separate string in the array. If set to ["mypy"], it will use the version of Mypy available in the PATH environment variable. Note: Using this option may slowdown type checking. Examples: - `["~/global_env/mypy"]` - `["conda", "run", "-n", "lint_env", "python", "-m", "mypy"]`
mypy-type-checker.interpreter	`[]`	Path to a Python executable or a command that will be used to launch the Mypy server and any subprocess. Accepts an array of a single or multiple strings. When set to `[]`, the extension will use the path to the selected Python interpreter. If passing a command, each argument should be provided as a separate string in the array.
mypy-type-checker.importStrategy	`useBundled`	Defines which Mypy binary to be used to type check Python files. When set to `useBundled`, the extension will use the Mypy binary that is shipped with the extension. When set to fromEnvironment, the extension will attempt to use the Mypy binary and all dependencies that are available in the currently selected environment. Note: If the extension can't find a valid Mypy binary in the selected environment, it will fallback to using the Mypy binary that is shipped with the extension. Note: The `mypy-type-checker.path` setting takes precedence and overrides the behavior of `mypy-type-checker.importStrategy`.
mypy-type-checker.usePerProjectEnvironments	`false`	Uses the selected Python environment for each project configured through `python-envs.pythonProjects`. Explicit `mypy-type-checker.path` and `mypy-type-checker.interpreter` settings take precedence.
mypy-type-checker.showNotifications	`off`	Controls when notifications are shown by this extension. Accepted values are `onError`, `onWarning`, `always` and `off`.
mypy-type-checker.reportingScope	`file`	(experimental) Controls the scope of Mypy's problem reporting. If set to `file`, Mypy will limit its problem reporting to the files currently open in the editor. If set to `workspace`, Mypy will extend its problem reporting to include all files within the workspace. If set to `custom`, Mypy will only report problems for files specified in the [Mypy configuration](https://mypy.readthedocs.io/en/stable/config_file.html#confval-files)
mypy-type-checker.preferDaemon	`true`	(experimental) Whether the Mypy daemon (`dmypy`) will take precedence over `mypy` for type checking. Note: if `mypy-type-checker.reportingScope` is set to `workspace`, enabling the Mypy daemon will offer a faster type checking experience. This setting will be overridden if `mypy-type-checker.path` is set.
mypy-type-checker.daemonStatusFile	`""`	(experimental) Path to the status file used by the Mypy daemon (`dmypy`).
mypy-type-checker.ignorePatterns	`[]`	Configure glob patterns as supported by the fnmatch Python library to exclude files or folders from being type checked by Mypy.

The following variables are supported for substitution in the mypy-type-checker.args, mypy-type-checker.cwd, mypy-type-checker.path, mypy-type-checker.interpreter and mypy-type-checker.ignorePatterns settings:

${workspaceFolder}
${workspaceFolder:FolderName}
${userHome}
${env:EnvVarName}

The mypy-type-checker.path setting also supports the ${interpreter} variable as one of the entries of the array. This variable is subtituted based on the value of the mypy-type-checker.interpreter setting.

Commands

Command	Description
Mypy: Restart Server	Force re-start the linter server.

Logging

From the Command Palette (View > Command Palette ...), run the Developer: Set Log Level... command. Select Mypy Type Checker from the Extension logs group. Then select the log level you want to set.

Alternatively, you can set the mypy-type-checker.trace.server setting to verbose to get more detailed logs from the Mypy server. This can be helpful when filing bug reports.

To open the logs, click on the language status icon ({}) on the bottom right of the Status bar, next to the Python language mode. Locate the Mypy Type Checker entry and select Open logs.

Troubleshooting

In this section, you will find some common issues you might encounter and how to resolve them. If you are experiencing any issues that are not covered here, please file an issue.

If the mypy-type-checker.importStrategy setting is set to fromEnvironment but Mypy is not found in the selected environment, this extension will fallback to using the Mypy binary that is shipped with the extension. However, if there are dependencies installed in the environment, those dependencies will be used along with the shipped Mypy binary. This can lead to problems if the dependencies are not compatible with the shipped Mypy binary.

To resolve this issue, you can:
- Set the mypy-type-checker.importStrategy setting to useBundled and the mypy-type-checker.path setting to point to the custom binary of Mypy you want to use; or
- Install Mypy in the selected environment.
If you have the reporting scope set to workspace and notice a slowdown in type checking, you can try enabling the Mypy daemon (dmypy) by setting the mypy-type-checker.preferDaemon setting to true.

Development

This extension bundles the shared vscode-common-python-lsp library as a git submodule at external/vscode-common-python-lsp. The submodule must be initialized before installing dependencies, because npm install builds the shared library from it.

When cloning the repository, pull the submodule at the same time:

git clone --recurse-submodules https://github.com/microsoft/vscode-mypy.git

If you already cloned without --recurse-submodules, initialize (or update) the submodule from the repository root:

git submodule update --init --recursive

Then choose the appropriate local package-feed setup below.

Local package feeds

Use Node.js supported by this repository and Python 3.10 or later. Both setup commands create or reuse .venv and install the Python bundling tools. Choose the appropriate setup below before installing dependencies. Committed lockfiles use public npm URLs; Microsoft setup rewrites working copies for proxy installs.

Public contributors (non-Microsoft employees)

Use the public setup, which selects https://registry.npmjs.org/ and https://pypi.org/simple/ for its child processes. No Microsoft account or internal-feed credentials are needed, and this command works before node_modules exists:

From the repository root:

npm run setup

For subsequent npm installs, use npm ci. Public contributors do not need the Microsoft feed commands or lockfile hook.

Microsoft employees only

Microsoft users only: The commands in this section configure Microsoft package feeds. Public contributors should use the public setup above.

Use the Microsoft setup, which selects https://packagefeedproxy.microsoft.io/npm/ and https://packagefeedproxy.microsoft.io/pypi/simple/ for its child processes:

npm run setup:msft

Microsoft setup initializes submodules, then rewrites public npm and Yarn resolved URLs in the root and shared TypeScript package-lock.json files to the npm proxy before running npm ci. Versions, integrity hashes, formatting, and private-feed URLs are preserved. The public setup leaves lockfiles unchanged.

After pulling a new lockfile from GitHub, rerun npm run setup:msft, or run the dependency-free rewrite step alone before your next install/build:

npm run setup:msft-registry

The standalone step requires the submodule to be initialized and both lockfiles to exist. Rewriting is idempotent and stops on missing or invalid lockfiles. Keep committed lockfile URLs public using the optional pre-commit hook below (or npm run normalize-lockfile for the root lockfile). The shared lockfile belongs to the submodule; do not commit its local proxy URL changes.

For subsequent root npm installs, use:

npm run ci:msft

This rewrites both lockfiles, then runs root npm ci with the proxy registry explicitly selected for package, audit, and metadata requests. It requires the submodule to be initialized; use npm run setup:msft for full setup, including the shared package and Python dependencies.

Local setup, lockfile rewriting, and ci:msft share the feed URLs in build/package-feeds.json.

Both setup commands use the same implementation, stop on errors, and keep registry overrides scoped to setup's child processes; they do not change your shell environment, edit .npmrc, or add credentials. The standalone rewrite step only edits lockfiles; it does not configure the registry for subsequent commands.

After setup, run npm run compile to build the extension. For subsequent Python commands, use .venv\Scripts\python.exe on Windows or .venv/bin/python on macOS/Linux (or activate that virtual environment). Registry overrides are not retained after setup.

Microsoft contributor pre-commit hook

If you use the Microsoft feeds and will commit changes, enable the recommended lockfile hook once per clone (no installed npm dependencies are required). It is not needed just to install or build:

npm run setup-hooks

The installer sets the clone's local core.hooksPath to .githooks, which also affects its linked worktrees. It refuses to replace an existing hook or a different hooks configuration. If you already use hooks, add node build/normalize-package-lock.js --staged to your existing pre-commit hook instead. Only enable this configuration in worktrees/branches that contain these hook files.

Before a local commit, the hook converts known Pylance_PublicPackages, packagefeedproxy.microsoft.io/npm/, and named 1es-public/npm-public mirror tarball URLs in the staged root package-lock.json to public npm URLs. It preserves versions, integrity hashes, formatting, and intentional Azure-hosted dependencies such as msft_consumption. Unknown feeds are left unchanged. It re-stages only the lockfile; if normalization is needed and the lockfile has unstaged changes, the commit is blocked without modifying it. Stage or stash those changes, then retry.

To normalize manually, run npm run normalize-lockfile, review the changes, and stage them. To disable the installed hook, run git config --local --unset core.hooksPath. These are local Git hooks: GitHub and Dependabot do not execute them. No workflow writes changes to PR branches.

GitHub Actions package feeds

The PR and push workflows set PIP_INDEX_URL to https://packagefeedproxy.microsoft.io/pypi/simple/ for pip and nox installs. Their Node installation steps select https://packagefeedproxy.microsoft.io/npm/ explicitly through npm run ci:msft, so these workflows do not set NPM_CONFIG_REGISTRY. CodeQL retains both environment variables because its autobuild step does not use the install helper. The npm endpoint follows the TypeScript CI package-feed-proxy job.

The shared lint and VSIX build actions and applicable PR/push test jobs use npm run ci:msft, rewriting working-copy lockfile URLs before installation and explicitly selecting the proxy for npm requests. Workflows do not commit these rewrites or change local registry configuration or Dependabot configuration. Existing dependency caches are retained; the VSIX build also retains its offline-cache preference. CodeQL retains workflow-level feed settings for its autobuild step.

Azure release package feeds

The DevDiv Azure stable/prerelease pipelines pass the npm proxy to their build/publish templates using customNPMRegistry. After initializing submodules, their dependency install steps use npm run ci:msft to rewrite both npm lockfiles and install through the proxy.

Each Python bootstrap and bundled-library install step explicitly sets PIP_INDEX_URL from PIP_PROXY_INDEX_URL, selecting the pip proxy even when a template's authentication setup changes the job-level index. Release triggers, approval gates, signing, and publishing behavior are unchanged.

Dependabot continues to use public registries and its existing update settings. Legacy Azure stable, prerelease, and validation definitions are unchanged.