1# Python
2
3Python support is available natively in Zed.
4
5- Tree-sitter: [tree-sitter-python](https://github.com/tree-sitter/tree-sitter-python)
6- Language Server: [microsoft/pyright](https://github.com/microsoft/pyright)
7
8## Configuration
9
10The [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.
11
12For more information, see the Pyright [configuration documentation](https://microsoft.github.io/pyright/#/configuration).
13
14## Settings
15
16The [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`.
17
18For example, in order to:
19
20- use strict type-checking level
21- diagnose all files in the workspace instead of the only open files default
22- provide the path to a specific Python interpreter
23
24```json
25{
26 "lsp": {
27 "pyright": {
28 "settings": {
29 "python.analysis": {
30 "diagnosticMode": "workspace",
31 "typeCheckingMode": "strict"
32 },
33 "python": {
34 "pythonPath": ".venv/bin/python"
35 }
36 }
37 }
38 }
39}
40```
41
42For more information, see the Pyright [settings documentation](https://microsoft.github.io/pyright/#/settings).
43
44## Virtual environments
45
46A 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.
47
48By 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.
49
50To do this, create a JSON file called `pyrightconfig.json` at the root of your project. This file must include two keys:
51
52- `venvPath`: a relative path from your project directory to any directory that _contains_ one or more virtual environment directories
53- `venv`: the name of a virtual environment directory
54
55For example, a common approach is to create a virtual environment directory called `.venv` at the root of your project directory with the following commands:
56
57```sh
58# create a virtual environment in the .venv directory
59python3 -m venv .venv
60# set up the current shell to use that virtual environment
61source .venv/bin/activate
62```
63
64Having done that, you would create a `pyrightconfig.json` with the following content:
65
66```json
67{
68 "venvPath": ".",
69 "venv": ".venv"
70}
71```
72
73If you prefer to use a `pyproject.toml` file, you can add the following section:
74
75```toml
76[tool.pyright]
77venvPath = "."
78venv = ".venv"
79```
80
81You can also configure this option directly in your `settings.json` file ([pyright settings](#settings)), as recommended in [Configuring Your Python Environment](https://microsoft.github.io/pyright/#/import-resolution?id=configuring-your-python-environment).
82
83```json
84{
85 "lsp": {
86 "pyright": {
87 "settings": {
88 "python": {
89 "pythonPath": ".venv/bin/python"
90 }
91 }
92 }
93 }
94}
95```
96
97## Code formatting & Linting
98
99The 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.
100
101A 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).
102
103## Virtual Environments in the Terminal {#terminal-detect_venv}
104
105Zed will also detect virtual environments and automatically activate them in terminal if available.
106See: [detect_venv documentation](../configuring-zed.md#terminal-detect_venv) for more.
107
108<!--
109TBD: Expand Python Ruff docs.
110TBD: Ruff pyproject.toml, ruff.toml docs. `ruff.configuration`.
111-->