Extension API

Topics Overview Your First Extension Extension Anatomy Wrapping Up Overview Common Capabilities Theming Extending Workbench Overview AI Extensibility Language Model Tool MCP Dev Guide Chat Participant Chat Tutorial Language Model Language Model Tutorial Language Model Chat Provider Prompt TSX Command Color Theme File Icon Theme Product Icon Theme Tree View Webview Notebook Custom Editors Virtual Documents Virtual Workspaces Web Extensions Workspace Trust Task Provider Source Control Debugger Extension Markdown Extension Test Extension Custom Data Extension Telemetry Overview Activity Bar Sidebars Panel Status Bar Views Editor Actions Quick Picks Command Palette Notifications Webviews Context Menus Walkthroughs Settings Overview Syntax Highlight Guide Semantic Highlight Guide Snippet Guide Language Configuration Guide Programmatic Language Features Language Server Extension Guide Embedded Languages Testing Extensions Publishing Extensions Bundling Extensions Continuous Integration Extension Host Remote Development and Codespaces Using Proposed API Migrate from TSLint to ESLint Python Extension Template VS Code API Contribution Points Activation Events Extension Manifest Built-In Commands When Clause Contexts Theme Color Product Icon Reference Document Selector

Authoring Python Extensions

Note: If you are new to VS Code extension authoring, you may want to read the Your First Extension tutorial first and try creating a simple Hello World extension.

The Python extension provides APIs for other extensions to work with Python environments available on the user's machine. Check out @vscode/python-extension npm module that includes types and helper utilities to access these APIs from your extension.

Python extension template

The Python extension template helps get you started building a Visual Studio Code extension for your favorite Python tool. It could be a linter, formatter, or code analysis, or all of those together. The template will give you the basic building blocks you need to build an extension that integrates your tool into VS Code, and it already has access to the Python APIs mentioned above.

Programming languages and frameworks

The extension template has two parts, the extension part and language server part. The extension part is written in TypeScript, and language server part is written in Python over the pygls (Python language server) library.

You will mostly be working on the Python part of the code when using this template. You will be integrating your tool with the extension part using the Language Server Protocol. pygls currently works on the version 3.16 of LSP.

The TypeScript part handles working with VS Code and its UI. The extension template comes with a few settings built-in that can be used by your tool. If you need to add new settings to support your tool, you will have to work with a bit of TypeScript. The extension template has examples for a few settings and you can also look at extensions developed by our team for some of the popular tools.

Requirements

VS Code 1.64.0 or greater
Python 3.7 or greater
node >= 14.19.0
npm >= 8.3.0 (npm is installed with node, check npm version, use npm install -g npm@8.3.0 to update)
Python extension for VS Code

You should know how to create and work with Python virtual environments.

Getting started

To get started, follow the instructions in the template README. There you will learn how to use the template to create your repository and how to install the necessary tools (for example, the nox task runner) and optional dependencies (testing support).

The README has the most up-to-date instructions and also goes into details on how to customize the extension's package.json placeholders (<pythontool-module>, <pythontool-display-name>, etc.).

Features of the template

After creating your extension via the template, it will include the following extension contributions. Assume <pytool-module> was replaced with mytool, and <pytool-display-name> withMy Tool:

A command My Tool: Restart Server (command ID: mytool.restart).
Following settings:
- mytool.logLevel
- mytool.args
- mytool.path
- mytool.importStrategy
- mytool.interpreter
- mytool.showNotification
Following triggers for extension activation:
- On Language python.
- On File with .py extension found in the opened workspace.
- On Command mytool.restart.
Output channel for logging Output > My Tool.

Integrating your tool

The generated bundled/tool/server.py file is where you will make most of your changes. TODO comments in the file point out the various customization points. Also search for TODO comments in other locations in the template, such as other Python and Markdown files. You will want to review the LICENSE file, even if you want to keep it MIT License.

Examples

There are several example implementations created from the template:

Pylint - implements linting and Code Actions on file open, save, and close.
Flake8 - implements linting and Code Actions.
Black Formatter - integrates the Black formatter.
autopep8 - integrates the autopep8 formatter.
isort - adds Code Actions to sort imports.

You can also review the Language Server Protocol specification to better understand the pygls language server integration.

Extension development

The template README goes into detail on the development cycle support included with the template. The template has commands and configurations so you can build, run, debug, and test your extension.

If you run into problems during development, there is a Troubleshooting section to help with common issues.

Packaging and publishing

Before publishing your extension, you'll need to update the extension package.json fields (such as publisher and license) for your specific extension. You also want to update the auxiliary Markdown files (CODE_OF_CONDUCT.md, CHANGELOG.md, etc.).

Once your extension is ready to publish, there is a nox build-package task to create a .vsix file, which you can then upload to your extension management page.

If you are new to creating and publishing VS Code extensions, we recommend you follow best practices outlined in the main VS Code extension authoring topics. Here you'll find guidance to help make your extension look great on the Marketplace and how to become a verified publisher so that the users feel confident installing your extension.

5/13/2026