配置 Python 解释器

PyCharm 中的 Python 解释器

要在 PyCharm 中使用您的 Python 代码，您需要至少配置一个 Python 解释器。您可以使用随 Python 安装提供的系统解释器。您还可以创建 Virtualenv、 pipenv、 Poetry、 uv、 hatch 或 conda 虚拟环境。虚拟环境由基础解释器和已安装的包组成。

使用 PyCharm Pro ，您还可以通过 SSH、 Docker、 Docker Compose 或 WSL（仅限 Windows）配置解释器，在远程环境中运行 Python 代码。

配置 Python 解释器时，您需要指定系统中 Python 可执行文件的路径。因此，在配置 Python 解释器之前，您需要确保已下载 Python并将其安装在系统中，并且您知道其路径。

您可以基于同一个 Python 可执行文件创建多个 Python 解释器。这在您需要为开发不同类型的应用程序创建不同的虚拟环境时非常有用。例如，您可以基于 Python 3.12 创建一个虚拟环境来开发 Django 应用程序，并基于相同的 Python 3.12 创建另一个虚拟环境来处理科学库。

Python 解释器可以为新项目或当前项目配置（您可以创建新解释器或使用现有解释器）。

配置现有的 Python 解释器

您可以随时通过使用 Python 解释器选择器或在设置中切换 Python 解释器。

Python 解释器选择器位于状态栏上。这是切换 Python 解释器最方便和最快捷的方式。单击它并选择目标解释器：

在 IDE 设置中切换 Python 解释器

按下 Ctrl+Alt+S 打开设置，然后选择项目 <project name> | Python 解释器。
单击下拉菜单并选择所需的 Python 解释器：
如果列表中没有，请单击显示全部。然后在左侧窗格中选择所需的解释器并单击确定。
当 PyCharm 停止支持任何过时的 Python 版本时，相应的 Python 解释器将被标记为不支持。

当您更改项目解释器并选择 SSH 解释器时，可能需要将本地内容与目标服务器同步。注意右下角的通知气泡：

您可以选择启用文件自动上传到服务器：

点击自动上传文件以在下次保存时开始上传。
点击同步并自动上传文件以立即同步文件并在将来每次保存时上传。

修改 Python 解释器

按下 Ctrl+Alt+S 打开设置，然后选择项目 <project name> | Python 解释器。
展开可用解释器列表并点击显示全部。
您可以在解释器路径(I) 字段中修改 Python 可执行文件的路径。
当启用将此虚拟环境与当前项目关联(A) 复选框时，解释器仅在当前 PyCharm 项目中可用。
要更改解释器名称，请选择目标解释器并单击。
在名称字段中指定的 Python 解释器名称将在可用解释器列表中可见。点击确定应用更改。

移除 Python 解释器

如果您不再需要项目中的 Python 解释器，可以将其从项目设置中移除。

请执行以下操作之一：
- 按下 Ctrl+Alt+S 打开设置，然后选择项目 <project name> | Python 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。
展开可用解释器列表并点击显示全部。
请选择您要删除的解释器，然后点击。

创建新的 Python 解释器

配置本地 Python 解释器

要为当前项目配置本地 Python 解释器，请按照以下任一过程操作：

创建 virtualenv 环境

请执行以下操作之一：
- 单击 Python Interpreter 选择器并选择添加新的解释器。
- 按下 Ctrl+Alt+S 以打开设置并导航到 Python | 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择添加本地解释器。
以下操作取决于您是要生成新的虚拟环境还是使用现有的虚拟环境。
新的 virtualenv 环境
1. 从环境类型列表中选择 Virtualenv。
2. 从列表中选择基础解释器，或者点击并在您的文件系统中找到 Python 可执行文件。
3. 在位置字段中指定新的虚拟环境的位置，或者点击并在您的文件系统中浏览位置。新虚拟环境的目录应为空。
4. 如果您希望将机器上全局 Python 中安装的所有包都添加到您将要创建的虚拟环境中，请选择从基础解释器继承包复选框。此复选框对应 --system-site-packages 选项的 virtualenv 工具。
5. 如果您希望在 PyCharm 中创建 Python 解释器时重用此环境，请选择向所有项目开放复选框。
现有的 virtualenv 环境
- 从环境类型列表中选择 Virtualenv。
- 从列表中选择所需的解释器。
  如果列表中没有所需的解释器，请点击，然后浏览以找到所需的 Python 可执行文件（例如，macOS 上的 venv/bin/python 或 Windows 上的 venv\Scripts\python.exe ）。
已选择的虚拟环境将为当前项目重复使用。
点击确定完成任务。

有关更多信息，请参阅配置一个 virtualenv 环境。

创建 conda 环境

确保 Anaconda 或 Miniconda 已下载并安装在您的计算机上，并且您知道其可执行文件的路径。
如需更多信息，请参阅安装说明。
请执行以下操作之一：
- 单击 Python Interpreter 选择器并选择添加新的解释器。
- 按下 Ctrl+Alt+S 以打开设置并导航到 Python | 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择添加本地解释器。
接下来的操作取决于您是要创建一个新的 conda 环境还是使用现有的环境。
新 conda 环境
1. 从环境类型列表中选择 Conda。
2. 从列表中选择 Python 版本。
3. 指定环境名称。
4. PyCharm 将检测 conda 安装。
  如果 PyCharm 未自动检测到安装，请指定 conda 可执行文件的位置，或单击浏览查找。
现有 conda 环境
1. 从环境类型列表中选择 Conda。
2. PyCharm 将检测 conda 安装。
  如果 PyCharm 未自动检测到安装，请指定 conda 可执行文件的位置，或单击浏览查找。
3. 从列表中选择环境。
所选的 conda 环境将被重新用于当前项目。
点击确定完成任务。

欲了解更多信息，请参阅配置一个 Conda 虚拟环境。

创建 pipenv 环境

请执行以下操作之一：
- 单击 Python Interpreter 选择器并选择添加新的解释器。
- 按下 Ctrl+Alt+S 以打开设置并导航到 Python | 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择添加本地解释器。
从环境类型列表中选择 Pipenv。
从列表中选择基础解释器，或者点击并在您的文件系统中找到 Python 可执行文件。
如果您已将基础二进制目录添加到您的 PATH 环境变量中，则无需设置任何其他选项：pipenv 可执行文件的路径将自动检测。
如果 PyCharm 未检测到 pipenv 可执行文件，请点击通过 pip 安装 pipenv 以允许 PyCharm 自动为您安装。
或者，按照 pipenv 安装过程发现可执行文件路径，然后在对话框中指定它。
点击确定完成任务。

当您将 pipenv 虚拟环境设置为 Python 解释器时，所有可用的软件包会从 Pipfile 中定义的源添加。可以通过 pipenv 而不是 pip 在包列表中安装、移除和更新包。

欲了解更多信息，请参阅配置 pipenv 环境。

创建一个 Poetry 环境

请执行以下操作之一：
- 单击 Python Interpreter 选择器并选择添加新的解释器。
- 按下 Ctrl+Alt+S 以打开设置并导航到 Python | 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择添加本地解释器。
以下操作取决于您是想创建一个新的 Poetry 环境还是使用一个现有的环境。
新的 Poetry 环境
1. 从环境类型列表中选择 Poetry。
2. 从列表中选择基础解释器，或者点击并在您的文件系统中找到 Python 可执行文件。
3. PyCharm 将检测 Poetry 安装。
  如果 PyCharm 未检测到 Poetry 安装，请单击通过 pip 安装 poetry 以允许 PyCharm 自动为您安装 Poetry。
  或者，请指定 Poetry 可执行文件的位置，或单击浏览查找。
现有 Poetry 环境
1. 确保项目目录包含一个 pyproject.toml 文件。
2. 从列表中选择解释器。
  如果列表中没有所需的解释器，请点击，然后在先前配置的 Poetry 环境中浏览所需的 Python 可执行文件。
所选的 Poetry 环境将用于当前项目。
点击确定完成任务。

欲了解更多信息，请参阅配置 Poetry 环境。

创建 uv 环境

请执行以下操作之一：
- 单击 Python Interpreter 选择器并选择添加新的解释器。
- 按下 Ctrl+Alt+S 以打开设置并导航到 Python | 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择添加本地解释器。
以下操作取决于您是要生成新的虚拟环境还是使用现有的虚拟环境。
新建 uv 环境
1. 从环境类型列表中选择 uv。
2. 从列表中选择 Python 版本。
3. PyCharm 将检测 uv 安装。
  如果 PyCharm 未自动检测到安装，请指定 uv 可执行文件的位置，或单击浏览查找。
现有的 uv 环境
1. 从环境类型列表中选择 uv。
2. PyCharm 将检测 uv 安装。
  如果 PyCharm 未自动检测到安装，请指定 uv 可执行文件的位置，或单击浏览查找。
3. 从列表中选择环境。
所选的 uv 环境将被重用于当前项目。
点击确定完成任务。

有关更多信息，请参见配置 uv 环境。

创建 Hatch 环境

请执行以下操作之一：
- 单击 Python Interpreter 选择器并选择添加新的解释器。
- 按下 Ctrl+Alt+S 以打开设置并导航到 Python | 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。单击可用解释器列表旁边的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择添加本地解释器。
以下操作取决于您是要生成新的虚拟环境还是使用现有的虚拟环境。
新建 Hatch 环境
1. 从环境类型列表中选择 Hatch。
2. PyCharm 将检测 Hatch 安装。
  如果 PyCharm 未自动检测到安装，请指定 Hatch 可执行文件的位置，或单击浏览查找。
3. 请选择一个环境。
  Hatch 环境是为各类特定项目任务设计的工作区。若未明确选择任何环境，Hatch 将使用默认环境。
4. 从列表中选择基础解释器，或者点击并在您的文件系统中找到 Python 可执行文件。
已有 Hatch 环境
1. 从环境类型列表中选择 Hatch。
2. PyCharm 将检测 Hatch 安装。
  如果 PyCharm 未自动检测到安装，请指定 Hatch 可执行文件的位置，或单击浏览查找。
3. 从列表中选择环境。
点击确定完成任务。

有关更多信息，请参见配置 Hatch 环境。

配置远程 Python 解释器

当添加远程 Python 解释器时，首先将 PyCharm 助手复制到远程主机。 PyCharm 助手用于远程运行打包任务、调试器、测试和其他 PyCharm 功能。

接下来，生成二进制库的骨架并复制到本地。此外，所有 Python 库源代码都会从远程主机上的 Python 路径中收集，并与生成的骨架一起复制到本地。本地存储骨架和所有 Python 库源代码是确保解析和补全正常工作的必要条件。

PyCharm 在每次远程运行时都会检查远程助手版本，因此如果您更新了 PyCharm 版本，新助手将自动上传，您无需重新创建远程解释器。

配置 WSL 解释器

请执行以下操作之一：
- 单击 Python Interpreter 选择器并选择添加新的解释器。
- 按下 Ctrl+Alt+S 以打开设置并导航到 Python | 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。单击可用解释器列表旁边的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择在 WSL 上。
等待 PyCharm 检测到您的计算机上的 Linux 并完成自检。单击下一个继续：
在对话框的左侧窗格中，选择您要创建的 WSL 解释器类型：虚拟环境、 Conda 环境或系统解释器。
对于系统解释器，只需提供所选 Linux 发行版中 Python 可执行文件的路径。
对于虚拟和 conda 环境，您可以提供所选 Linux 发行版中现有环境的 Python 可执行文件路径，或基于指定的 Python 创建新环境。

完成后，新解释器将被添加到您的项目中，并设置默认的 mnt 映射。

欲了解更多信息，请参阅使用 WSL 配置解释器。

使用 SSH 配置解释器

请确保远程主机上运行着一个 SSH 服务器，因为 PyCharm 通过 ssh-session 运行远程解释器。
请执行以下操作之一：
- 单击 Python Interpreter 选择器并选择添加新的解释器。
- 按下 Ctrl+Alt+S 以打开设置并导航到 Python | 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择通过 SSH。
选择一个选项以创建新的 SSH 连接，然后指定服务器信息（主机、端口和用户名）。
或者，您可以选择现有并从列表中选择任何可用的 SSH 配置。要创建新的 SSH 配置，请按照以下步骤操作：
创建 SSH 配置
- 单击配置列表旁边的。
- 单击，禁用仅对此项目可见复选框，并填写所需字段：
- 完成后，新创建的 SSH 配置将出现在可用配置列表中。它还将在 SSH 部署配置设置中可用。点击下一个继续：
在下一个对话框窗口中，提供连接目标服务器的身份验证详细信息。
选择密码或密钥对(OpenSSH 或 PuTTY) 并输入您的密码或密码短语。如果密钥对(OpenSSH 或 PuTTY) 被选中，请指定：
- 私钥：私钥文件的位置
- 密码短语：类似于密码，它用于加密私钥。
点击下一个继续。
等待 PyCharm 完成对 SSH 服务器的自检。
在下一个对话框中，选择要在 SSH 服务器上配置的 Python 环境类型。
您可以创建一个新的虚拟环境或 conda 环境，选择一个现有的，或者使用系统解释器。
- 如果您希望将机器上全局 Python 中安装的所有包都添加到您将要创建的虚拟环境中，请选择从基础解释器继承包复选框。此复选框对应 --system-site-packages 选项的 virtualenv 工具。
- 如果您需要以 sudo 用户身份在 SSH 服务器上执行 Python 代码，请启用通过 sudo 以 root 权限执行代码复选框。
- 您可以配置本地项目与服务器之间的路径映射。为此，请点击浏览图标，位于同步文件夹字段中，并输入本地项目文件夹的路径以及远程服务器上文件夹的路径。
单击创建完成添加解释器。

有关更多信息，请参见使用 SSH 配置解释器。

使用 Docker 配置解释器

请执行以下操作之一：
- 单击 Python Interpreter 选择器并选择添加新的解释器。
- 按下 Ctrl+Alt+S 以打开设置并导航到 Python | 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。单击可用解释器列表旁边的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择在 Docker 上。
在 Docker 服务器下拉菜单中选择一个现有的 Docker 配置。
或者，点击并执行以下步骤以创建新的 Docker 配置：
创建 Docker 配置
点击以添加 Docker 配置，并指定如何连接到 Docker 守护进程。
连接设置取决于您的 Docker 版本和操作系统。如需更多信息，请参阅 Docker connection settings。
连接成功消息应出现在对话框的底部。
有关在 Windows 或 macOS 上使用 Docker 时将本地路径映射到运行 Docker 守护进程的虚拟机的更多信息，请参阅 Windows 和 macOS 主机的虚拟机路径映射。您将无法对映射本地路径之外的目录使用卷和绑定挂载。
此表在 Linux 主机上不可用，在该主机上 Docker 本地运行，您可以将任何目录挂载到容器。

以下操作取决于您是要从 Docker 注册表中拉取预构建的镜像，还是从 Dockerfile 本地构建镜像。

拉取 Docker 镜像

选择拉取或使用现有镜像并在镜像标记字段中指定所需镜像的标签。

构建 Docker 镜像

选择构建并在必要时更改 Dockerfile 和上下文文件夹字段中的默认值。

如果需要，展开可选部分并指定以下内容：

镜像标记

为生成的镜像指定一个可选名称和标签。

这对将来参考图像会有所帮助。如果您将该字段留空，图像将只有一个随机唯一标识符。

构建选项

设置支持的 docker build 选项。

例如，您可以使用 --label 选项为构建的镜像指定元数据。

构建实参

指定构建时变量的值，这些变量在构建过程中可以像常规环境变量一样访问，但不会在中间或最终镜像中持久存在。

这与使用 --build-args 选项和 docker build 命令相似。

这些变量必须通过 ARG 指令在 Dockerfile 中定义。例如，您可以为即将使用的基础镜像版本定义一个变量：

                        ARG PY_VERSION=latest

                        FROM python:$PY_VERSION

在这种情况下， PY_VERSION 变量将默认为 latest ，并且 Dockerfile 将生成一个具有最新可用 Python 版本的镜像，除非您将其重新定义为构建时参数。如果设置了 PY_VERSION=3.10 ，Docker 将拉取 python:3.10 ，运行一个带有 Python 3.10 版本的容器。

将 PY_VERSION 参数重新定义类似于设置以下命令行选项：

--build-arg PY_VERSION=3.10

您可以提供用空格分隔的多个参数。

等待 PyCharm 连接到 Docker 守护进程并完成容器自省。
接下来，选择一个解释器以在 Docker 容器中使用。您可以选择容器中已配置的任何 virtualenv 或 conda 环境，或者选择系统解释器。
点击确定。
配置的远程解释器已添加到列表中。

有关更多信息，请参见使用 Docker 配置解释器。

使用 Docker Compose 配置解释器

请执行以下操作之一：
- 单击 Python Interpreter 选择器并选择添加新的解释器。
- 按下 Ctrl+Alt+S 以打开设置并导航到 Python | 解释器。
- 单击 Python Interpreter 选择器并选择解释器设置。单击可用解释器列表旁边的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择在 Docker Compose 上。
在服务器下拉菜单中选择 Docker 配置。
请在 docker-compose.yml 文件中指定配置文件并选择服务。
可选地，指定环境变量并编辑 Compose 项目名称。
等待 PyCharm 创建并配置新的目标：
选择一个解释器以在容器中使用。您可以选择容器中已配置的任何 virtualenv 或 conda 环境，或者选择系统解释器。
点击确定。
配置的远程解释器已添加到列表中。

有关更多信息，请参阅使用 Docker Compose 配置解释器。

设置默认解释器

在 PyCharm 中，您可以指定一个默认解释器。首次打开不包含 .idea 文件夹的所有现有项目时，它将自动设置。

转到文件 | 新建项目设置 | 新项目的设置。
选择 Python 解释器设置。然后从 Python 解释器列表中选择一个现有解释器，或点击以添加新解释器。点击确定保存更改。

管理解释器包

对于每个解释器，您可以安装、升级和删除 Python 包。默认情况下，PyCharm 使用 pip 管理项目包。对于 conda 环境，您可以使用 conda 包管理器。

PyCharm 智能地跟踪包的状态，并通过显示当前安装的包版本（列版本）和最新可用版本（列最新版本）来识别过时版本。当检测到包的新版本时，PyCharm 会用箭头符号标记它，并建议升级。

默认情况下，最新版本列仅显示包的稳定版本。如果您希望将最新可用版本的范围扩展到任何预发布版本（例如测试版或候选发布），请点击显示早期版本。

您可以一次升级多个包。按住 Cmd （macOS）或 Ctrl （Unix 或 Windows），左键点击以选择包列表中的多个项目，然后点击升级。

请参阅详细说明：

如果您正在寻找一种更方便的方式来搜索 Python 包、预览文档和管理 Python 包存储库，请尝试 Python 软件包工具窗口。更多信息请参阅在 Python Packages 工具窗口中管理软件包。

最后修改日期： 2025年 9月 26日

PyCharm 2025.2 Help

配置 Python 解释器

PyCharm 中的 Python 解释器

配置现有的 Python 解释器

使用 Python Interpreter 选择器切换 Python 解释器

在 IDE 设置中切换 Python 解释器

修改 Python 解释器

移除 Python 解释器

创建新的 Python 解释器

配置本地 Python 解释器

创建 virtualenv 环境

创建 conda 环境

创建 pipenv 环境

创建一个 Poetry 环境

创建 uv 环境

创建 Hatch 环境

配置远程 Python 解释器

配置 WSL 解释器

使用 SSH 配置解释器

使用 Docker 配置解释器

使用 Docker Compose 配置解释器

设置默认解释器

管理解释器包