How to configure VS Code for type checking in a uv project
Pylance’s type-checking mode defaults to off, but a project’s Pyright configuration can override it. To enable its bundled checker, follow Pylance’s diagnostics setup; no separate checker dependency is needed. For a uv-managed project using another checker, this guide also covers ty with the official ty extension, and mypy with Microsoft’s Mypy Type Checker extension.
.venv directory. If you haven’t set one up yet, see create your first Python project.Pick the right extension
The handbook leans toward Pyrefly for a new project, with ty a close alternative. Match an established project’s checker instead of changing it to follow an editor recipe. See the checker comparison for project-specific tradeoffs.
| Route | Editor setup | Project configuration |
|---|---|---|
| Pyrefly | Pylance’s selectable diagnostics backend | [tool.pyrefly] or pyrefly.toml |
| ty | astral-sh.ty extension |
[tool.ty] |
| mypy | ms-python.mypy-type-checker extension alongside Pylance |
[tool.mypy] |
For Pyrefly, start with Pylance’s diagnostics backend. The ty and mypy recipes serve projects using those checkers.
Set up the ty extension
Add ty as a dev dependency:
uv add --dev tyInstall the ty extension (astral-sh.ty) from the VS Code Marketplace. Its default importStrategy is fromEnvironment, so it finds the ty binary in .venv automatically after uv sync.
Keep Pylance or let ty replace it
Pylance (bundled with the Python extension) and ty are both language servers: each provides completions, go-to-definition, hover documentation, and type-error diagnostics. Running both produces duplicate diagnostics.
The ty extension resolves this by disabling Pylance when it activates, setting python.languageServer to None. Keep this default when you want ty to own every language-server feature.
To keep Pylance’s IntelliSense alongside ty’s type checking, switch ty into type-checking-only mode:
{
"python.languageServer": "Pylance",
"ty.disableLanguageServices": true
}With ty.disableLanguageServices set to true, ty reports type errors as diagnostics but leaves completions and hover to Pylance. Use this when adopting ty incrementally.
Check the whole workspace
By default, ty reports diagnostics only for open files (ty.diagnosticMode is openFilesOnly). To see type errors across the whole project, set it to workspace:
{
"ty.diagnosticMode": "workspace"
}Point ty at the venv interpreter
ty discovers .venv/ without extra configuration. If the environment lives in a non-standard location, or imports stay unresolved after uv sync, set ty.interpreter (a list whose first entry is used):
{
"ty.interpreter": [".venv/bin/python"]
}Note
ty is in beta as of 2026. If Pylance provides a feature ty doesn’t yet support, run them together in type-checking-only mode rather than letting ty disable Pylance.
Set up the mypy extension
mypy uses the Mypy Type Checker extension (ms-python.mypy-type-checker). It only reports diagnostics, so Pylance keeps handling IntelliSense and no language-server conflict arises.
Add mypy as a dev dependency:
uv add --dev mypyThen install the extension from the Marketplace and configure it:
{
"mypy-type-checker.importStrategy": "fromEnvironment",
"mypy-type-checker.reportingScope": "workspace"
}Use the venv mypy, not the bundled copy
The extension defaults importStrategy to useBundled, shipping its own mypy. For a uv project that causes two problems: the bundled mypy can differ from the version pinned in pyproject.toml, and it can’t see third-party type stubs installed with uv add --dev. Setting importStrategy to fromEnvironment makes the extension use the mypy in the active environment, which is the .venv uv creates. Run uv sync before opening VS Code so mypy is present.
reportingScope: "workspace" reports errors across the whole project instead of only open files (the default is file).
Keep daemon mode enabled
The extension defaults preferDaemon to true, keeping a dmypy process alive between saves so incremental checks are fast. No extra configuration is needed. If the daemon gets into a bad state after a dependency change, stop it and let VS Code restart it on the next check:
uv run dmypy stopSet the working directory in a monorepo
The extension runs mypy with ${workspaceFolder} as the working directory, matching the project root where pyproject.toml lives. When the mypy configuration lives in a subdirectory, point cwd at it:
{
"mypy-type-checker.cwd": "${workspaceFolder}/backend"
}cwd also accepts ${fileDirname} (run from the checked file’s directory) and ${nearestConfig} (run from the nearest ancestor directory containing a mypy configuration file).
Resolve imports across a uv workspace
First verify package installation with the interpreter VS Code selected. Declare sibling dependencies and their workspace sources, then sync the selected package. At a root with a [project] table, use uv sync --all-packages when the environment should include every member. A virtual root with no [project] table installs all members by default. Sharing a lockfile alone does not declare dependencies between members.
If runtime imports work but Pylance cannot resolve an editable package, follow the editable-install troubleshooting steps. Add source roots only for a deliberate source-only setup or a verified backend import-hook limitation, not to hide a missing dependency.
For a deliberate source-only layout, Pylance’s python.analysis.extraPaths and mypy’s mypy_path are separate settings. Prefer a TOML list for multiple mypy paths so the configuration avoids platform-specific path separators.
Choose Pylance’s diagnostics backend
Pylance uses Pyright by default. Enable its built-in type checking without a separate project dependency:
{
"python.analysis.typeCheckingMode": "standard"
}The modes are off (default), basic, standard, and strict. standard checks annotated code and infers types for most patterns; strict enables additional diagnostics, matching Pyright configured with typeCheckingMode = "strict". Pyright has no --strict command-line flag.
Pylance reads [tool.pyright] in pyproject.toml, as well as pyrightconfig.json and python.analysis.* editor settings. pyrightconfig.json takes precedence over [tool.pyright]; either project configuration overrides the editor’s type-checking mode. It does not read [tool.mypy] or [tool.ty].
Pylance also supports Pyrefly through the Type Server Protocol. Select Pylance + Pyrefly in the Diagnostics Source setting to keep Pylance’s editor features and use Pyrefly’s type analysis. Pylance locates or downloads Pyrefly; project checking then follows Pyrefly’s configuration rather than [tool.pyright]. See Microsoft’s setup instructions and Pyrefly’s integration guide.
Use the same checker version and project environment in CI. For a Pyrefly project, initialize [tool.pyrefly] or pyrefly.toml; its unconfigured basic preset suppresses many type errors.
Restart the language server after switching setups
After changing the interpreter or switching extensions, the language server can hold stale state. Reset it from the Command Palette:
- ty: ty: Restart server
- mypy: Mypy: Restart Server