Skip to content

FAQ.md

Latest commit

 

History

History
159 lines (109 loc) · 10.3 KB

FAQ.md

File metadata and controls

159 lines (109 loc) · 10.3 KB

Pylance Frequently Asked Questions

General Questions

What is the relationship between Pylance, Pyright and the Python extension?

Pylance is a language server, which provides features like IntelliSense, logical linting (e.g., errors and warnings), code actions, code navigation, semantic colorization, etc. Pyright is the open-source type checker which Pylance uses under the hood to provide its functionality. Pylance provides a superset of Pyright's functionality. To use Pylance, you must have the core Python extension installed in Visual Studio Code as it builds upon that experience.

What features are in Pylance but not in Pyright? What is the difference exactly?

Pylance has a handful of valuable features that are not available in Pyright, including semantic highlighting, refactoring code actions (extract variable/extract method), docstrings for built-in/standard library modules, and IntelliCode compatibility. Pylance also ships with a collection of type stubs for popular modules to provide fast and accurate auto-completions and type checking.

Are there any plans to open-source Pylance in the future?

Because we have plans to include Pylance in Microsoft products outside of VS Code that do not have the same license, business models and/or are closed-source (for example, fully managed products and services), we do not currently have plans to open-source Pylance.

However, a substantial portion of Pylance's source code is open source via the Pyright type checker. We welcome contributions via that repository, and feedback on Pylance via our pylance-release repo.

Can I load Pylance in Code – OSS?

Pylance is licensed for use in Microsoft products and services only, so can only be used on official Microsoft builds of Visual Studio Code and GitHub Codespaces.

What telemetry and user data do you collect? Can I opt out?

You can read about how we collect and use telemetry, including how to disable it, here.

Installation and Setup

How do I install Pylance?

Pylance comes bundled as an optional dependency with the Python extension. Simply install the Python extension from the VS Code marketplace, and Pylance will be installed automatically. Open any Python (.py) file to activate it.

What is the minimum VS Code version required for Pylance?

Pylance requires VS Code version 1.57 or above.

How do I switch to Pylance from another language server?

If you've previously set a different language server, update your settings.json file with: "python.languageServer": "Pylance" or "python.languageServer": "Default". You can also use the Settings Editor UI to make this change.

Configuration and Performance

What are the different language server modes (light/default/full)?

Pylance offers three predefined modes via the python.analysis.languageServerMode setting:

  • default: Balanced experience with many useful features enabled. Suitable for most users.
  • light: Lightweight, memory-efficient setup with fewer features. Ideal for resource-constrained environments or when you prefer minimal IntelliSense.
  • full: Most extensive feature set with all capabilities enabled. Provides the richest IntelliSense experience but uses more resources.

You can override individual settings regardless of which mode you choose.

Why is Pylance using so much memory?

Large projects can cause Pylance to use significant memory. To reduce memory usage:

  1. Use light mode: Set "python.analysis.languageServerMode": "light" in settings.json
  2. Exclude unnecessary files: Add "python.analysis.exclude": ["**/testFiles/*.py", "**/node_modules/**"] to exclude files you don't need analyzed
  3. Use openFilesOnly diagnostic mode: Set "python.analysis.diagnosticMode": "openFilesOnly" to only analyze open files
  4. Provide a custom Node.js executable: Set "python.analysis.nodeExecutable": "auto" to use a version without memory limits (see TROUBLESHOOTING.md for details)

What's the difference between diagnosticMode settings?

  • openFilesOnly (default): Only analyzes files you have open in the editor. Faster and uses less memory.
  • workspace: Analyzes all Python files in your workspace. Finds more issues but uses more resources.

What type checking modes are available?

Pylance offers four type checking modes via python.analysis.typeCheckingMode:

  • off (default): No type checking analysis; only shows unresolved imports/variables
  • basic: Basic type checking rules
  • standard: Standard type checking rules (more strict)
  • strict: Strictest type checking with all rules enforced

Note: This can be overridden by pyrightconfig.json or pyproject.toml configuration files.

Import and Module Resolution

Why do I get "Import X could not be resolved" warnings?

This usually happens for one of these reasons:

  1. Package not installed: Install the package using pip install package-name
  2. Wrong Python environment: Ensure VS Code is using the correct Python interpreter (check the bottom-left status bar)
  3. Custom project structure: If you have a sources or custom directory structure, add it to python.analysis.extraPaths: 
    {
    "python.analysis.extraPaths": ["./sources", "./my_custom_dir"]
}

See TROUBLESHOOTING.md for more details.

How do I configure Pylance to find my own modules?

Create a .vscode/settings.json file in your workspace and add the directories containing your modules to python.analysis.extraPaths:

{
    "python.analysis.extraPaths": ["./src", "./lib"]
}

Relative paths are relative to the workspace root. The src directory is automatically detected, so no configuration is needed for standard src layouts.

Why can't Pylance find my editable install modules?

Pylance requires editable installs to use .pth files rather than import hooks. Configure your package manager to use path-based editable installs:

  • pip/setuptools: Use compat mode or strict mode (see setuptools documentation)
  • uv: Add config-settings = { editable_mode = "compat" } to [tool.uv] in pyproject.toml
  • Hatchling: Uses path-based .pth files by default
  • PDM: Uses path-based .pth files by default

See TROUBLESHOOTING.md for detailed instructions.

Virtual Environments and Interpreters

How do I select the correct Python interpreter?

Click on the Python version in the bottom-left status bar of VS Code, or use the command palette (Ctrl+Shift+P / Cmd+Shift+P) and search for "Python: Select Interpreter". Choose the interpreter from your virtual environment.

Does Pylance work with conda environments?

Yes, Pylance works with conda environments. Make sure to select the conda environment's Python interpreter using the Python extension's interpreter selector.

Does Pylance work with Poetry, pipenv, or other virtual environment managers?

Yes, Pylance works with all virtual environment managers. Just ensure you've selected the correct Python interpreter from your virtual environment in VS Code.

Framework and Tool Integration

Does Pylance work with Jupyter Notebooks?

Yes, Pylance has native Jupyter Notebooks compatibility. Open any .ipynb file in VS Code and Pylance will provide IntelliSense and type checking within notebook cells.

Does Pylance support pytest?

Yes, Pylance has pytest support enabled by default in default and full modes. You can explicitly enable it with "python.analysis.enablePytestSupport": true.

How do I configure Pylance for Django projects?

For Django projects, you may need to add your Django app directories to python.analysis.extraPaths if you encounter import resolution issues. Also consider creating type stubs for Django-specific features that might not be fully typed.

Troubleshooting

Pylance is not starting or shows an error on startup

Ensure you're running an official build of VS Code (not VS Codium or other variants). Pylance only works with official VS Code builds and GitHub Codespaces. If the problem persists, check the Output panel (View > Output > Python Language Server) for error messages.

Why are packages not resolving when using WSL?

When using Pylance with WSL (Windows Subsystem for Linux), make sure your workspace is located under a WSL folder (/home/...) and not on a Windows-shared path (/mnt/...). See issue #1443 for more details.

How do I disable specific diagnostic rules?

You can disable specific diagnostics in your settings.json or pyrightconfig.json. For example:

{
    "python.analysis.diagnosticSeverityOverrides": {
        "reportUnusedVariable": "none",
        "reportGeneralTypeIssues": "warning"
    }
}

See the diagnostics documentation for a full list of available diagnostic rules.

How do I report issues or get help?

Check TROUBLESHOOTING.md first for common issues. If your problem isn't covered, file an issue on the pylance-release repository with logs (enable with "python.analysis.logLevel": "Trace") and a code example to reproduce the issue.

Advanced Configuration

Can I use a custom type stub directory?

Yes, you can specify custom type stub directories using python.analysis.stubPath in your settings.json. By default, Pylance looks for stubs in a typings directory in your workspace root.

How do I configure Pylance with pyrightconfig.json or pyproject.toml?

Pylance respects configuration in pyrightconfig.json or the [tool.pyright] section of pyproject.toml. These files allow you to configure type checking behavior, include/exclude paths, and more. See the Pyright configuration documentation for details.

Can I use Pylance in a multi-root workspace?

Yes, Pylance has native multi-root workspace support. Place .vscode/settings.json in the root directory of each workspace for workspace-specific configuration.