--- title: "Python" description: "基于 basedpyright 和 Ruff 的 Python 代码智能、解释器与虚拟环境识别、pytest 和 Django 运行，以及基于 debugpy 的调试。" --- OpenIDEA 通过类型检查语言服务器（默认 basedpyright）提供 Python 代码智能；如果项目配置了 Ruff，还会同时启动 Ruff 服务器。IDE 会自动找到本机的解释器和虚拟环境，用项目解释器运行脚本、pytest 和 Django 测试，并用 debugpy 调试。其他语言的情况见[支持矩阵](/zh/languages/index)。 ## 语言服务器 Python 文件（`.py`、`.pyi`、`.pyw`、`SConstruct`、`SConscript`，以及 shebang 中含 `python` 的文件）同一时间只由一个类型检查器提供服务，Ruff 另外并行： | 服务器 | 作用 | 安装方式 | | ------------ | ------------------------------------------------ | ----------------------- | | basedpyright | 默认类型检查器：补全、跳转、悬停提示、诊断、重构 | pip，装进独立的虚拟环境 | | Pyright | 仅在未安装 basedpyright 时使用 | npm | | ty | 仅在以上两者都未安装时使用 | pip，装进独立的虚拟环境 | | Pyrefly | 仅在以上都未安装时使用 | pip，装进独立的虚拟环境 | | Ruff | 代码检查、格式化、整理导入、一键修复 | pip，装进独立的虚拟环境 | basedpyright 以 `standard` 类型检查模式启动，而不是它自带的更严格的默认模式。项目里的 `pyproject.toml` 中的 `[tool.basedpyright]` 或 `pyrightconfig.json` 仍然优先。 Ruff 只为位于 Ruff 配置之下的文件启动：`ruff.toml`、`.ruff.toml`，或包含 `[tool.ruff]` 表的 `pyproject.toml`。basedpyright 本身不提供格式化，格式化由 Ruff 负责。 想手动指定类型检查器，打开 **设置 › 语言和框架 › 语言服务器**，选中这四个服务器中的任意一个，修改 **Python 语言服务器**。**自动** 会按上表顺序使用第一个已安装的服务器；也可以固定选一个，或选 **无**。 ## 环境配置 ### 安装语言服务器 打开 Python 文件时如果缺少服务器，OpenIDEA 会弹出类似 **basedpyright 未安装** 的通知，点 **安装** 即可。也可以在 **设置 › 语言和框架 › 语言服务器** 中安装、重新安装，或者指定你自己的可执行文件。 - basedpyright、ty、Pyrefly 和 Ruff 会装进 IDE 工具文件夹里的独立虚拟环境。`PATH` 上有 uv 时用 uv，否则用 `python3 -m venv`。前提是本机装有 Python 3 或 uv。 - Pyright 通过 npm 安装，需要 Node.js。 - 不会往你项目的环境里装任何东西。 工具文件夹位于本地数据目录下，见[数据目录与日志](/zh/reference/data-directories)。 ### 解释器与虚拟环境 项目解释器按以下顺序确定： 1. **设置 › 语言和框架 › Python 解释器** 中选定的解释器。 2. 项目里的虚拟环境：`.venv`、`venv`、`env` 或 `.env`（含 `pyvenv.cfg` 的目录），或 `.pixi/envs/` 下的 pixi 环境。 3. 项目通过 mise 或 asdf 固定的 Python 版本（`mise.toml`、`.tool-versions` 等 mise 配置文件）。 该页面的解释器列表还会列出 IDE 在本机找到的解释器：当前激活的 `VIRTUAL_ENV`，virtualenvwrapper、pipenv 和 Poetry 创建的虚拟环境，pyenv 的各个版本，uv 安装的 Python，mise 和 asdf 的安装，conda 环境（Miniconda、Anaconda、Miniforge、Mambaforge、micromamba，以及 `conda env list` 能看到的所有环境），还有 `PATH` 上的 `python` 可执行文件。 选定的解释器会传给 basedpyright 和 Pyright（`python.pythonPath`），其虚拟环境会作为 `VIRTUAL_ENV` 提供给语言服务器和运行配置。 状态栏上的 **Python 解释器** 显示当前解释器，点击可以切换，也可以打开 **添加新的解释器…** 和 **解释器设置…**。 ### 创建环境 在 **设置 › 语言和框架 › Python 解释器** 中选择 **添加 Python 解释器**，再选 **解释器类型**： - **Virtualenv 环境**：用你选的基础解释器执行 `python -m venv`。 - **uv 环境**：执行 `uv venv --python `（`PATH` 上需要有 uv）。 - **Poetry 环境**：在项目中执行 `poetry env use `。 - **Conda 环境**：执行 `conda create -p `，Python 版本与基础解释器一致。 也可以直接选择已有的解释器或环境目录。新解释器会成为项目解释器。 ### 软件包 同一页面会列出所选解释器已安装的软件包，可以搜索、按名称 **安装**、**升级** 和 **卸载**。IDE 使用解释器自带的 pip；没有 pip 的环境（uv 创建的环境默认如此）改用 `uv pip`。 页面上的其他选项： - **激活 virtualenv**（**终端** 分组）：新的终端会话会运行虚拟环境的激活脚本。 - **文档字符串格式**（**文档字符串** 分组）：纯文本、reStructuredText、Epytext、NumPy 或 Google。文档字符串里的标签和关键字按该格式高亮。 ### 格式化 **重新格式化代码**（`⌘⌥L` / `Ctrl+Alt+L`）使用 Ruff。在 **设置 › 语言和框架 › Ruff** 中可以设置 Ruff 路径、配置目录、**格式化工具**（**自动（优先语言服务器）** 或 Ruff）以及 **保存时运行**。不指定配置目录时，Ruff 读取最近的 `pyproject.toml`（`[tool.ruff]`）、`ruff.toml` 或 `.ruff.toml`。 ## 运行与测试 在包含 `pyproject.toml`、`setup.py`、`setup.cfg`、`requirements.txt`、`pytest.ini`、`tox.ini`、`manage.py` 或项目虚拟环境的目录里，OpenIDEA 会自动识别这些运行配置： | 配置 | 条件 | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `python -m ` | 项目根目录或 `src/` 下有包含 `__main__.py` 的包 | | `pytest` | 项目使用 pytest：存在 `pytest.ini`、`tox.ini`、`conftest.py`，`setup.cfg` 中有 `[tool:pytest]`，`pyproject.toml` 或 requirements 文件提到 pytest，或环境中装有 pytest | | `manage.py runserver` | 存在 `manage.py`（Django） | | `manage.py test` | 存在 `manage.py`（Django 测试） | 工具会通过项目的包管理器运行：有 `uv.lock` 时用 `uv run`，有 `poetry.lock` 时用 `poetry run`，有 `pdm.lock` 时用 `pdm run`，否则用 `.venv` 或 `venv` 中的工具，pixi 环境则用 `pixi run`。如果在设置中选了解释器，运行配置会直接使用它。 编辑器左侧栏的图标可以运行或调试： - 文件中的 `if __name__ == "__main__":` 代码块； - pytest 的 `test_*` 函数和 `Test*` 类； - `unittest.TestCase` 子类及其测试方法。 即使项目没有声明任何测试配置，测试文件也可以用 pytest 运行（用项目解释器执行 `python -m pytest`，因此该解释器里要装有 pytest）。在 Django 项目中，`TestCase` 测试也可以用 `manage.py test` 运行。pytest 和 Django unittest 运行器的结果显示在测试树中，**重新运行失败的测试** 只重跑失败的用例。 也可以在 **运行 › 编辑配置…** 中新建 **pytest** 和 **Django 测试** 配置。详见[运行配置](/zh/guide/run)和[测试](/zh/guide/testing)。 | 操作 | macOS | Windows / Linux | | -------------- | ----- | ---------------- | | 运行上下文配置 | `⌃⇧R` | `Ctrl+Shift+F10` | | 调试上下文配置 | `⌃⇧D` | 无 | **使用覆盖率运行** 使用项目解释器中的 coverage.py，**性能分析** 使用 py-spy。缺少时 IDE 会提示，并给出安装命令（例如 uv 项目中的 `uv add --dev coverage`）。详见[覆盖率](/zh/guide/coverage)和[性能分析](/zh/guide/profiler)。 Jupyter Notebook（`.ipynb`）在 Python 解释器上运行，见 [Notebook](/zh/guide/notebook)。 ## 调试 Python 调试使用 debugpy。开始调试时如果缺少 debugpy，OpenIDEA 会提示安装。IDE 在自己的工具文件夹里保存一份 debugpy，并把它加载到运行程序的解释器中，所以项目环境里不需要安装 debugpy。 - 可以调试脚本、`python -m` 模块，以及 `pytest`、`uvicorn` 这类命令行入口。通过 `uv run`、`poetry run`、`pdm run`、`pipenv run`、`hatch run` 或 `rye run` 启动的程序会在对应管理器的环境中运行。 - 调试 `manage.py` 时会开启 debugpy 的 Django 支持。 - **附加到进程…**（`⌥⇧F5` / `Ctrl+Alt+F5`）会在 **Python (debugpy)** 分组下列出本机的 Python 进程。 - **Python 远程调试 (debugpy)** 配置可以附加到用 `python -m debugpy --listen` 启动的进程，本机或远程机器都可以，并支持本地与远程根目录映射。 相关选项： - **设置 › 构建、执行、部署 › Python 调试器**：**调试时自动附加到子进程** 和 **兼容 Gevent**。 - **设置 › 构建、执行、部署 › 调试器 › 单步执行**：**不要步入库脚本**（即 debugpy 的 `justMyCode`）。 断点、单步和调试工具窗口的用法见[调试](/zh/guide/debugging)。 ## 框架支持 目前只有 Django 有专门支持：`manage.py runserver` 和 `manage.py test` 运行配置、**Django 测试** 配置类型（目标、settings 模块、选项）、在左侧栏运行单个 `TestCase` 测试，以及调试器的 Django 模式。Flask、FastAPI 等其他框架按普通脚本或命令行入口运行。 ### Django 模板 Django 项目（上层目录有 `manage.py`）中 `templates` 目录里的 HTML 和文本文件以 **Django Template** 打开：模板标签、变量、过滤器和注释在 HTML 之上高亮，块标签（`{% block %}`、`{% if %}`、`{% for %}`、`{% with %}` 以及 Django 和其 contrib 库的其他块标签）可以折叠、缩进内容并高亮对应的结束标签。输入 `{%`、`{{` 或 `{#` 会自动补全成对符号，写完块标签会自动添加结束标签，输入 `{% end` 会补全当前打开块的结束标签。**使用行注释** 会把每一行放进各自的 `{# … #}`，多行的 **使用块注释** 则用 `{% comment %}`。HTML 语言服务器和 Emmet 在标签之间的标记中照常工作。 其他位置含有 Django 标签的 HTML 文件会显示一个横幅，可以切换为 Django Template 或保留为 HTML；两种选择都会成为该文件的 **覆盖文件类型**。 ## 限制 - 同一时间只运行一个类型检查器。Ruff 只在有 Ruff 配置的项目中运行。 - 代码智能和诊断都来自语言服务器，IDE 自身不做 Python 分析。 - 覆盖率和性能分析需要你的环境中装有 coverage.py 和 py-spy，IDE 不自带这两个工具。 - 左侧栏的运行图标基于逐行扫描，不常见的测试写法可能没有图标，但仍可以通过 pytest 配置运行。