当前位置：首页 > news >正文

【Python】PyCharm + poetry 管理 Python 虚拟环境

news 2026/7/16 23:21:14

Windows 使用 PyCharm + poetry 管理 Python 虚拟环境，完全舍弃Anaconda

1. 确保安装Python

关键前提：Poetry 管理多版本虚拟环境的核心是系统中必须已安装对应版本的 Python。它不会自动下载或安装 Python，而是依赖系统中已存在的解释器。因此，需要哪个版本的虚拟环境，就先在系统中安装该版本的 Python 即可。

安装 Python 12 时可以选择安装到其他磁盘（如 D 盘、E 盘等），并非只能安装到 C 盘。

具体操作步骤（以 Windows 系统为例）：

从 Python官网地址下载 Python 12（可以选择自己需要的版本）的安装包（.exe 文件）。
运行安装包，首先勾选底部的 “Add Python.exe to PATH”（非常重要，否则后续命令行可能无法直接调用 Python）。
点击 “Customize installation”（自定义安装），而非默认的 “Install Now”。
在 “Optional Features” 页面保持默认选项，点击 “Next”。
在 “Advanced Options” 页面，找到 “Install location” 选项，点击右侧的 “Browse”，选择你希望安装的路径（例如 D:\Python\Python12）。
确认路径后，点击 “Install” 完成安装。

注意事项：

安装路径建议避免包含中文、空格或特殊符号（如 D:\我的软件\Python 12 可能会导致后续使用问题），尽量使用纯英文路径（如 D:\Python12）。
无论安装到哪个磁盘，只要勾选了 “Add Python to PATH”，命令行中输入 python --version 或
python3 --version 就能正常识别安装的版本，Poetry 也能自动找到该 Python 解释器。

这样就可以将 Python 12 安装到非 C 盘，同时不影响后续使用 Poetry 管理虚拟环境。

当前系统只装了 Python 12 时Poetry 会默认使用 Python 12 作为基础解释器来创建虚拟环境，此时你只能创建 Python 12 版本的虚拟环境（因为系统中没有其他版本的 Python 可供选择）。后续需要更高版本的 Python 时只需在系统中额外安装更高版本的 Python（例如 Python 13），并确保安装时勾选 “Add Python to PATH”（让 Poetry 能在系统中找到该版本）。之后，在需要使用更高版本的项目中，通过修改项目的 pyproject.toml 文件指定目标版本即可，例如：

[tool.poetry.dependencies]python="^3.13"# 指定需要 Python 13 及以上版本`

2. 安装 Poetry、PyCharm 关联 poetry 虚拟环境

在已安装 Python 的基础上，要在 PyCharm 中用 Poetry 管理项目虚拟环境，需按以下步骤操作：

步骤 0：修改 Poetry 的默认安装路径

Poetry 并非只能安装在 C 盘，它的默认安装路径虽然在系统盘（通常是 C 盘），但可以通过配置修改安装路径。不过需要注意的是，Poetry 的安装路径和它管理的虚拟环境路径是两个概念，下面分别说明：

Poetry 自身的安装路径（可修改）
Poetry 的默认安装路径如下：
- Windows：C:\Users\用户名\AppData\Roaming\Python\Scripts\（脚本路径）和 C:\Users\用户名\AppData\Local\pypoetry\（核心文件）
如果想修改 Poetry 自身的安装路径，需要在安装时通过环境变量指定。以 Windows 为例，步骤如下：
打开 PowerShell，先设置 POETRY_HOME 环境变量（指定自定义安装路径）：
```
$env:POETRY_HOME="D:\Program Files\Poetry"# 替换为你的目标路径
```
注意：此设置仅在当前会话有效
你通过 $env:POETRY_HOME = … 设置的环境变量是临时的，关闭当前 PowerShell 窗口后会失效。

步骤 1：安装 Poetry

设置好 POETRY_HOME 后，继续在系统中安装 Poetry，打开终端（Windows 用 PowerShell / 命令提示符），执行对应命令：

(Invoke-WebRequest-Urihttps://install.python-poetry.org -UseBasicParsing).Content|python -

此时 Poetry 会安装到你指定的 D:\Program Files\Poetry 路径下。安装完成后，还需要将 D:\Program Files\Poetry\bin（或 Scripts 目录）添加到系统 PATH 中，确保能直接在命令行使用 poetry 命令。

安装完成后，关闭并重新打开终端，输入 poetry --version 验证是否安装成功（显示版本号即正常）。

步骤 2：修改 Poetry 管理的虚拟环境路径（推荐修改，避免占 C 盘）

更重要的是虚拟环境的路径（项目依赖和解释器存放的地方），默认路径通常在 C 盘（如 C:\Users\用户名.virtualenvs\），长期使用会占用大量空间，建议修改到其他磁盘。

修改虚拟环境路径的方法：

打开终端，执行以下命令设置默认虚拟环境路径（以 D 盘为例）：
```
# Windows PowerShellpoetry config virtualenvs.path"D:\Program Files\Poetry"
```
验证设置是否生效：
```
poetry config--list# 查看配置，确认 virtualenvs.path 已更新
```
之后，Poetry 新建的虚拟环境都会存放在你指定的路径下，避免占用 C 盘空间。

步骤 3：PyCharm 创建 / 打开 Python 项目并初始化 Poetry

情况 A：新建项目

打开 PyCharm，点击 “New Project”，选择项目保存路径（例如
D:\my_poetry_project），暂时不要选择虚拟环境（后续由 Poetry 创建），点击 “Create”。
在 PyCharm 底部打开 “Terminal”（终端），输入以下命令初始化 Poetry 项目：
```
poetry new.# 注意末尾的点，表示在当前项目目录初始化
```
执行后，项目会生成 pyproject.toml（核心配置文件）、poetry.lock（依赖锁定文件）等 Poetry 所需文件。

情况 B：已有项目且已有requirement.txt

注意：
requirement.txt中不能有空行，不能有注释行

打开 PyCharm 的 “Terminal”，进入项目根目录，执行初始化命令：
```
poetry init
```
在 pyproject.toml 中禁用 “包模式”（适合非打包项目）
如果你的项目只是普通脚本（不需要打包成 Python 包发布），可以永久禁用 Poetry 的 “包模式”，避免检查 README.md 等打包相关文件：
打开项目根目录的 pyproject.toml 文件（poetry init 生成的配置文件）。
在文件末尾添加以下配置：
```
[tool.poetry]package-mode=false# 禁用包模式，仅用于依赖管理
```
执行以下命令创建虚拟环境（会自动使用你之前设置的默认路径）：
```
poetryinstall
```
在PyCharm中配置解释器
通过下面代码可添加所有依赖包，
```
poetryadd$(Get-Content requirement.txt)
```

情况 C：已有项目

在 PyCharm 中打开现有项目（例如 D:\existing_project）。
打开 PyCharm 的 “Terminal”，进入项目根目录，执行初始化命令：
```
poetry init
```

poetry init 是交互式初始化项目配置的过程，每一步提示都有默认值（括号中的内容），直接按回车即可使用默认值，无需额外填写。以下是针对当前提示及后续步骤的填写建议：
第一个提示：Package name []:
含义：项目的包名称（用于标识项目，通常与文件夹名一致）。
操作：直接按回车，使用默认值（括号中已显示，与你的项目文件夹名匹配，无需修改）。
后续其他提示的处理（参考以下建议）：
Version [0.1.0]:
含义：项目版本号（遵循语义化版本，如 0.1.0 表示初始版本）。
操作：直接回车，使用默认 0.1.0（后续可在 pyproject.toml 中修改）。
Description []:
含义：项目描述（简要说明项目用途）。
操作：可直接回车留空（非必填），也可输入描述（如 A route planning project）。
Author [Your Name you@example.com, n to skip]:
含义：作者信息（格式为姓名 <邮箱>）。
操作：若不想填写，输入 n 后回车；若想填写，按格式输入（如张三 zhangsan@example.com）。
License []:
含义：开源许可证（如 MIT、Apache 等，非必填）。
操作：直接回车留空（个人项目通常无需填写）。
Compatible Python versions [^3.12]:
含义：项目兼容的 Python 版本（默认匹配你安装的 Python 12）。
操作：直接回车，使用默认 ^3.12（表示支持 3.12 及以上兼容版本，与你的环境匹配）。
最后确认：Would you like to define your main dependencies interactively? (yes/no) [no]:
含义：是否交互式添加依赖（如 requests、pandas 等）。
操作：直接回车选 no（后续可通过 poetry add 包名更方便地添加依赖）。
二次确认：Would you like to define your development dependencies interactively? (yes/no) [no]:
含义：是否交互式添加开发依赖（如 pytest 测试工具）。
操作：直接回车选 no（需要时再用 poetry add --dev 包名添加）。
最终确认：Do you confirm generation? (yes/no) [yes]:
操作：直接回车选 yes，生成 pyproject.toml 文件。
总结：整个过程中，除了作者信息可能需要手动输入或跳过，其他步骤全部按回车使用默认值即可，无需额外配置。完成后，项目根目录会生成 pyproject.toml，接下来就可以执行 poetry install 创建虚拟环境了。

创建一个空的 README.md 文件
Poetry 只是需要 README.md 存在，内容可以为空。
在项目根目录（D:\existing_project）下，手动创建一个名为 README.md 的空文件（右键 → 新建 → 文本文档，重命名为 README.md，注意去掉 .txt 后缀）。
在 pyproject.toml 中禁用 “包模式”（适合非打包项目）
如果你的项目只是普通脚本（不需要打包成 Python 包发布），可以永久禁用 Poetry 的 “包模式”，避免检查 README.md 等打包相关文件：
打开项目根目录的 pyproject.toml 文件（poetry init 生成的配置文件）。
在文件末尾添加以下配置：
```
[tool.poetry]package-mode=false# 禁用包模式，仅用于依赖管理
```
执行以下命令创建虚拟环境（会自动使用你之前设置的默认路径）：
```
poetryinstall
```
- 首次执行会在你设置的默认路径（如 D:\Program Files\PoetryEnvs）中创建该项目的独立虚拟环境。
- 若项目无依赖，仅创建基础环境；若有依赖，会自动安装到虚拟环境中。
在 PyCharm 中关联 Poetry 虚拟环境（设置解释器）
- 打开 PyCharm 配置：「File → Settings → Project: 项目名 → Python Interpreter」。
  点击右上角的「Add Interpreter」（+ 号），选择「Add Local Interpreter」。
- 在弹出的窗口中，选择「Poetry Environment」，然后：
  - 自动识别：若 PyCharm 已识别到当前项目的 Poetry 环境（显示路径为你设置的默认路径），直接点击「OK」。
  - 手动选择：若未识别，点击「…」按钮，手动定位虚拟环境的 Python 解释器：
    ① 先在 Terminal 中执行 poetry env info --path，获取虚拟环境路径（例如 D:\PoetryEnvs\my_project-abc123）。
    ② 进入该路径，找到 Scripts\python.exe（Windows 系统），选中该文件。
    点击「OK」完成关联，PyCharm 会显示虚拟环境中已安装的依赖包。
后续常用操作（在 PyCharm Terminal 中）
- 安装新依赖：poetry add 包名（如 poetry add pandas）。
- 安装开发依赖（如测试工具）：poetry add --dev pytest。
- 卸载依赖：poetry remove 包名。
- 激活虚拟环境终端：poetry shell（命令行前缀会显示环境名称）。
- 直接运行脚本：poetry run python 脚本名.py（无需手动激活环境）。
- 查看已安装依赖： poetry show
完成以上步骤后，你的项目就会完全使用 Poetry 管理的虚拟环境，依赖隔离且路径可控，后续开发无需担心环境冲突问题。