配置 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 打开设置，然后选择 Python | 解释器。
点击下拉列表并选择所需的 Python 解释器：
如果列表中没有它，请点击显示全部。然后在左侧窗格中选择所需的解释器，并点击确定。
当 PyCharm 停止支持任何过时的 Python 版本时，相应的 Python 解释器将标记为不受支持。

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

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

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

修改 Python 解释器

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

移除 Python 解释器

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

执行以下任一操作：
- 按 Ctrl+Alt+S 打开设置，然后选择 Python | 解释器。
- 点击 Python 解释器选择器并选择解释器设置。
展开可用解释器列表，然后点击显示全部。
选择要移除的解释器，然后点击。

创建新的 Python 解释器

配置本地 Python 解释器

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

创建 virtualenv 环境

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

有关详细信息，请参阅配置 virtualenv 环境。

创建 conda 环境

确保已在您的计算机上下载并安装 Anaconda 或 Miniconda ，并且您知道其可执行文件的路径。
有关详细信息，请参阅 installation instructions。
执行以下任一操作：
- 点击 Python 解释器选择器并选择添加新解释器。
- 按 Ctrl+Alt+S 打开设置并导航到 Python | 解释器。
- 点击 Python 解释器选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择添加本地解释器。
接下来的操作取决于您是要创建新的 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 解释器选择器并选择添加新解释器。
- 按 Ctrl+Alt+S 打开设置并导航到 Python | 解释器。
- 点击 Python 解释器选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择添加本地解释器。
在环境类型列表中选择 Pipenv。
从列表中选择基础解释器，或点击，在文件系统中找到 Python 可执行文件。
如果您已将基础二进制目录添加到您的 PATH 环境变量中，则无需设置任何其他选项：将自动检测到 pipenv 可执行文件的路径。
如果 PyCharm 未检测到 pipenv 可执行文件，请点击通过 pip 安装 pipenv ，允许 PyCharm 自动为您安装它。
或者，按照 pipenv 安装过程查找可执行文件路径，然后在对话框中进行指定。
点击确定以完成该任务。

当您将 pipenv 虚拟环境设置为 Python 解释器后，所有可用包都将从 Pipfile 中定义的源添加。这些包将通过 pipenv（而非 pip）在包列表中进行安装、移除和更新。

有关详细信息，请参阅配置 pipenv 环境。

创建 Poetry 环境

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

有关详细信息，请参阅配置 Poetry 环境。

创建 uv 环境

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

有关详细信息，请参阅配置 uv 环境。

创建 Hatch 环境

执行以下任一操作：
- 点击 Python 解释器选择器并选择添加新解释器。
- 按 Ctrl+Alt+S 打开设置并导航到 Python | 解释器。
- 点击 Python 解释器选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择添加本地解释器。
接下来的操作取决于您是要生成新的虚拟环境还是使用现有的虚拟环境。
新建 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 解释器选择器并选择添加新解释器。
- 按 Ctrl+Alt+S 打开设置并导航到 Python | 解释器。
- 点击 Python 解释器选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择在 WSL 上。
等待 PyCharm 在您的机器上检测到 Linux 并完成内省。点击下一步继续：
在对话框左侧窗格中，选择要创建的 WSL 解释器类型：虚拟环境、 Conda 环境或系统解释器。
对于系统解释器，只需提供所选 Linux 发行版中 Python 可执行文件的路径。
对于虚拟环境和 conda 环境，您可以提供所选 Linux 发行版中现有环境的 Python 可执行文件路径，或基于指定的 Python 创建新环境。

一旦完成，新的解释器将添加到您的项目中，并将设置默认 mnt mappings。

有关详细信息，请参阅使用 WSL 配置解释器。

使用 SSH 配置解释器

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

有关详细信息，请参阅使用 SSH 配置解释器。

使用 Docker 配置解释器

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

接下来的操作取决于您是要从 Docker 注册表拉取预构建的镜像，还是根据 Dockerfile 在本地构建镜像。

拉取 Docker 镜像

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

构建 Docker 镜像

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

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

镜像标记

为构建的镜像指定可选的名称和标签。

这有助于将来引用该镜像。如果将该字段留空，镜像将只有一个随机唯一标识符。

构建选项

设置支持的 docker build 选项。

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

构建实参

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

这类似于使用 --build-args 选项与 docker build 命令。

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

                        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 解释器选择器并选择添加新解释器。
- 按 Ctrl+Alt+S 打开设置并导航到 Python | 解释器。
- 点击 Python 解释器选择器并选择解释器设置。点击可用解释器列表旁的添加解释器链接。
点击可用解释器列表旁的添加解释器链接并选择在 Docker Compose 上。
在服务器下拉列表中选择 Docker 配置。
在配置文件中指定 docker-compose.yml 文件，并选择服务。
可选地，指定环境变量，并编辑 Compose 项目名称。
等待 PyCharm 创建并配置新的目标：
选择要在容器中使用的解释器。您可以选择容器中已配置的任意 virtualenv 或 conda 环境，或选择系统解释器。
点击确定。
配置好的远程解释器将添加到列表中。

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

设置默认解释器

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

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

管理解释器软件包

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

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

默认情况下，最新版本列仅显示软件包的稳定版本。如果您想将最新可用版本的范围扩展到任何预发行版本（例如 beta 或 release candidate ），点击显示早期版本。

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

请参阅详细说明：

如果您正在寻找更便捷的方式来搜索 Python 软件包、预览文档并管理 Python 软件包存储库，请试用 Python 软件包工具窗口。有关详细信息，请参阅在 Python Packages 工具窗口中管理软件包。

最后修改日期： 2025年 12月 2日

PyCharm 2025.3 Help

配置 Python 解释器

PyCharm 中的 Python 解释器

配置现有 Python 解释器

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

在 IDE 设置中切换 Python 解释器

修改 Python 解释器

移除 Python 解释器

创建新的 Python 解释器

配置本地 Python 解释器

创建 virtualenv 环境

创建 conda 环境

创建 pipenv 环境

创建 Poetry 环境

创建 uv 环境

创建 Hatch 环境

配置远程 Python 解释器

配置 WSL 解释器

使用 SSH 配置解释器

使用 Docker 配置解释器

使用 Docker Compose 配置解释器

设置默认解释器

管理解释器软件包