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.
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.
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.
- VS Code 1.64.0 or greater
- Python 3.7 or greater
- node >= 14.19.0
- npm >= 8.3.0 (
npmis installed with node, check npm version, use
npm install -g firstname.lastname@example.org update)
- Python extension for VS Code
You should know how to create and work with Python virtual environments.
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 (
Features of the template
After creating your extension via the template, it will include the following extension contributions. Assume
<pytool-module> was replaced with
- A command My Tool: Restart Server (command ID:
- Following settings:
- Following triggers for extension activation:
- On Language
- On File with
.pyextension found in the opened workspace.
- On Command
- On Language
- Output channel for logging Output > My Tool.
Integrating your tool
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.
There are several example implementations created from the template:
- Pylint - implements linting and Code Actions on file
- 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.
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
license) for your specific extension. You also want to update the auxiliary Markdown files (
Once your extension is ready to publish, there is a
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.