配置 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 并完成内省。单击下一条继续：
生成新的或选择已存在的 Python 环境。},{
您可以选择 virtualenv、 conda 或 uv 环境类型。

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

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

使用 SSH 配置解释器

请确保远程主机上正在运行 SSH 服务器，因为 PyCharm 通过 ssh-sessions 运行远程解释器。
请执行下列任一操作：
- 点击 Python 解释器选择器，然后选择添加新解释器。
- 按 Ctrl+Alt+S 打开设置，并导航到 Python | 解释器。
- 点击 Python 解释器选择器，然后选择解释器设置。单击可用解释器列表旁边的添加解释器链接。
点击可用解释器列表旁边的添加解释器链接，并选择通过 SSH。
选择创建新 SSH 连接的选项，然后指定服务器信息（主机、端口和用户名）。
或者，您可以选择现有，并从列表中选择任一可用的 SSH 配置。要创建新的 SSH 配置，请执行以下步骤：
创建 SSH 配置
- 点击配置列表旁边的。
- 点击，禁用仅对此项目可见复选框，并填写必填字段：
- 完成后，新建的 SSH 配置将显示在可用配置列表中。它也会在 SSH 部署配置设置中可用。点击下一个以继续：
在下一个对话框中，提供连接到目标服务器所需的身份验证详细信息。
选择密码或密钥对(OpenSSH 或 PuTTY) ，并输入您的密码或口令。如果选择了密钥对(OpenSSH 或 PuTTY) ，请指定：
- 私钥：私钥文件的位置
- 密码短语：类似于密码，它用于加密私钥。
点击下一个继续。
请等待 PyCharm 完成对 SSH 服务器的探测。
生成新的或选择已存在的 Python 环境。},{
您可以选择 virtualenv、 conda 或 uv 环境类型。

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

使用 Docker 配置解释器

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

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

使用 Docker Compose 配置解释器

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

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

设置默认解释器

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

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

管理解释器软件包

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

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

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

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

请参阅详细说明：

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

2026年 3月 24日

PyCharm 2026.1 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 配置解释器

设置默认解释器

管理解释器软件包