1# Python
2
3Python support is available natively in Zed.
4
5- Tree-sitter: [tree-sitter-python](https://github.com/zed-industries/tree-sitter-python)
6- Language Servers:
7 - [microsoft/pyright](https://github.com/microsoft/pyright)
8 - [python-lsp/python-lsp-server](https://github.com/python-lsp/python-lsp-server) (PyLSP)
9- Debug Adapter: [debugpy](https://github.com/microsoft/debugpy)
10
11## Language Servers
12
13Zed supports multiple Python language servers some of which may require configuration to work properly.
14
15See: [Working with Language Servers](https://zed.dev/docs/configuring-languages#working-with-language-servers) for more information.
16
17## Virtual Environments in the Terminal {#terminal-detect_venv}
18
19Zed will detect Python virtual environments and automatically activate them in terminal if available.
20See: [detect_venv documentation](../configuring-zed.md#terminal-detect_venv) for more.
21
22## PyLSP
23
24[python-lsp-server](https://github.com/python-lsp/python-lsp-server/), more commonly known as PyLSP, by default integrates with a number of external tools (autopep8, mccabe, pycodestyle, yapf) while others are optional and must be explicitly enabled and configured (flake8, pylint).
25
26See [Python Language Server Configuration](https://github.com/python-lsp/python-lsp-server/blob/develop/CONFIGURATION.md) for more.
27
28## PyRight
29
30### PyRight Configuration
31
32The [pyright](https://github.com/microsoft/pyright) language server offers flexible configuration options specified in a JSON-formatted text configuration. By default, the file is called `pyrightconfig.json` and is located within the root directory of your project. Pyright settings can also be specified in a `[tool.pyright]` section of a `pyproject.toml` file. A `pyrightconfig.json` file always takes precedence over `pyproject.toml` if both are present.
33
34For more information, see the Pyright [configuration documentation](https://microsoft.github.io/pyright/#/configuration).
35
36### PyRight Settings
37
38The [pyright](https://github.com/microsoft/pyright) language server also accepts specific LSP-related settings, not necessarily connected to a project. These can be changed in the `lsp` section of your `settings.json`.
39
40For example, in order to:
41
42- use strict type-checking level
43- diagnose all files in the workspace instead of the only open files default
44- provide the path to a specific Python interpreter
45
46```json
47{
48 "lsp": {
49 "pyright": {
50 "settings": {
51 "python.analysis": {
52 "diagnosticMode": "workspace",
53 "typeCheckingMode": "strict"
54 },
55 "python": {
56 "pythonPath": ".venv/bin/python"
57 }
58 }
59 }
60 }
61}
62```
63
64For more information, see the Pyright [settings documentation](https://microsoft.github.io/pyright/#/settings).
65
66### Pyright Virtual environments
67
68A Python [virtual environment](https://docs.python.org/3/tutorial/venv.html) allows you to store all of a project's dependencies, including the Python interpreter and package manager, in a single directory that's isolated from any other Python projects on your computer.
69
70By default, the Pyright language server will look for Python packages in the default global locations. But you can also configure Pyright to use the packages installed in a given virtual environment.
71
72To do this, create a JSON file called `pyrightconfig.json` at the root of your project. This file must include two keys:
73
74- `venvPath`: a relative path from your project directory to any directory that _contains_ one or more virtual environment directories
75- `venv`: the name of a virtual environment directory
76
77For example, a common approach is to create a virtual environment directory called `.venv` at the root of your project directory with the following commands:
78
79```sh
80# create a virtual environment in the .venv directory
81python3 -m venv .venv
82# set up the current shell to use that virtual environment
83source .venv/bin/activate
84```
85
86Having done that, you would create a `pyrightconfig.json` with the following content:
87
88```json
89{
90 "venvPath": ".",
91 "venv": ".venv"
92}
93```
94
95If you prefer to use a `pyproject.toml` file, you can add the following section:
96
97```toml
98[tool.pyright]
99venvPath = "."
100venv = ".venv"
101```
102
103You can also configure this option directly in your `settings.json` file ([pyright settings](#pyright-settings)), as recommended in [Configuring Your Python Environment](https://microsoft.github.io/pyright/#/import-resolution?id=configuring-your-python-environment).
104
105```json
106{
107 "lsp": {
108 "pyright": {
109 "settings": {
110 "python": {
111 "pythonPath": ".venv/bin/python"
112 }
113 }
114 }
115 }
116}
117```
118
119### Code formatting & Linting
120
121The Pyright language server does not provide code formatting or linting. If you want to detect lint errors and reformat your Python code upon saving, you'll need to set up.
122
123A common tool for formatting Python code is [Ruff](https://docs.astral.sh/ruff/). It is another tool written in Rust, an extremely fast Python linter and code formatter. It is available through the [Ruff extension](https://github.com/zed-industries/zed/tree/main/extensions/ruff/). To configure the Ruff extension to work within Zed, see the setup documentation [here](https://docs.astral.sh/ruff/editors/setup/#zed).
124
125<!--
126TBD: Expand Python Ruff docs.
127TBD: Ruff pyproject.toml, ruff.toml docs. `ruff.configuration`.
128-->
129
130## Debugging
131
132Zed supports zero-configuration debugging of Python module entry points and pytest tests.
133Run {#action debugger::Start} ({#kb debugger::Start}) to see a contextual list for the current project.
134For greater control, you can add debug configurations to `.zed/debug.json`. See the examples below.
135
136### Debug Active File
137
138```json
139[
140 {
141 "label": "Python Active File",
142 "adapter": "Debugpy",
143 "program": "$ZED_FILE",
144 "request": "launch"
145 }
146]
147```
148
149### Flask App
150
151For a common Flask Application with a file structure similar to the following:
152
153```
154.venv/
155app/
156 init.py
157 main.py
158 routes.py
159templates/
160 index.html
161static/
162 style.css
163requirements.txt
164```
165
166…the following configuration can be used:
167
168```json
169[
170 {
171 "label": "Python: Flask",
172 "adapter": "Debugpy",
173 "request": "launch",
174 "module": "app",
175 "cwd": "$ZED_WORKTREE_ROOT",
176 "env": {
177 "FLASK_APP": "app",
178 "FLASK_DEBUG": "1"
179 },
180 "args": [
181 "run",
182 "--reload", // Enables Flask reloader that watches for file changes
183 "--debugger" // Enables Flask debugger
184 ],
185 "autoReload": {
186 "enable": true
187 },
188 "jinja": true,
189 "justMyCode": true
190 }
191]
192```