基于 pyenv-win 和 Poetry 构建 Python 开发环境

Hakuna 2024-02-08 2025-01-02 4357 字 22 minutes Python

Table of Content

简介

构建和维护一个高效、可靠的 Python 开发环境至关重要。为了实现这一目标，开发者可以选择多种工具来搭建自己的开发环境，包括但不限于 virtualenv、venv、conda、pipenv、poetry 以及 pyenv。每种工具都有其独特的特点和优势，但本文档将重点介绍在 Windows 系统下，如何利用 pyenv-win 和 Poetry 这两个工具来构建一个 Python 开发环境。

pyenv-win 是 pyenv（一个流行的多版本 Python 管理工具，面向与 MacOS 和 Linux 系统）的 Windows 版本（表述不严谨，其实 pyenv-win 和 pyenv 是两个独立（由不同的小组维护）的命令行工具，pyenv-win 在 Windows OS下实现了 pyenv 的功能）。它为开发者在同一 Windows OS 下提供了安装、管理，切换多个 Python 版本的解决方案。对于不同项目需要不同 Python 版本的开发者来说非常有用。

Poetry是一个 Python 依赖管理和打包工具。类似于 virtualenv、venv、conda、pipenv 所实现的功能。比较而言，Poetry 使用 pyproject.toml 文件来定义项目的依赖和配置，该方法提供了比传统 setup.py 文件更清晰、更直观的依赖声明方式。此外，Poetry 自带的依赖解析器能够自动解决依赖冲突，确保项目依赖的一致性和项目的可重复性。

安装指南

前提条件

Windows 7 或更高版本。
PowerShell 5 或更高版本（推荐使用 PowerShell 7）。
git。

安装 pyenv-win

pyenv-win 官方提供了多种安装方式，具体可以查看：pyenv for windows。这里，推荐使用 Git Commands的方式。

打开 Windows 系统的终端（Windows Terminal）软件。如下图所示：

左边显示的 Powershell 5，Windows 10 或者 11 自带。而右边的是 Powershell 7，需要单独安装。这两个版本均可以使用，但推荐使用 Powershell 7。可以在打开的终端界面中输入如下命令，确认 Powershell 的版本：

1

$PSVersionTable

安装 pyenv-win：在终端中使用 git clone 命令，将 pyenv-win 克隆到 “$HOME/.pyenv” 目录。
1

git clone https://github.com/pyenv-win/pyenv-win.git "$HOME/.pyenv"

在终端中使用 git clone 命令的前提是需要您在您的电脑中已经安装了 git 这个工具，具体可以参考官方安装流程：https://git-scm.com/downloads/
“$HOME/.pyenv” 目录指的是当前用户名下的，名为.pyenv 的文件夹。比如我在终端中输入如下命令：
```
$HOME
```
则会显示我的电脑用户名的路径 C:\Users\rolfz。
所以 git clone https://github.com/pyenv-win/pyenv-win.git "$HOME/.pyenv" 的意思是将 github 上名为 pyenv-win 的 repo 内容复制到我电脑用户名（即 C:\Users\rolfz）下的，名为 .pyenv 的文件夹下。当执行完改行命令后，如果在终端中使用 dir或者 ls 命令，你将会看见多出了一个 .pyenv 的文件夹。如果进入这个文件夹，您将会看见如下类似的内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


# 用户名下的内容
PS C:\Users\rolfz> ls


    目录: C:\Users\rolfz


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        2024/12/19     19:40                .config
d-----        2024/12/23     11:35                .dbus-keyrings
d-----        2024/12/26     21:39                .matplotlib
d-----        2024/12/19     19:42                .pyenv    # <---- 由 git clone 命令创建的文件夹
d-----        2024/12/20     12:21                .ssh
d-----        2024/12/19     19:30                .vscode
d-r---        2024/12/19     18:22                Contacts
d-r---        2024/12/31     19:37                Desktop
d-r---        2024/12/24     19:36                Documents
dar---          2025/1/2     12:50                Downloads
d-r---        2024/12/19     18:22                Favorites
d-r---        2024/12/19     18:22                Links
d-r---        2024/12/19     18:22                Music
dar---        2024/12/19     18:28                OneDrive
d-r---        2024/12/19     18:27                Pictures
d-r---        2024/12/19     18:22                Saved Games
d-----        2024/12/19     19:40                scoop
d-r---        2024/12/19     18:42                Searches
d-----        2024/12/19     19:29                source
d-r---        2024/12/19     18:22                Videos
d-----          2025/1/2     10:40                Zotero
-a----          2025/1/2     18:39             77 .git-credentials
-a----        2024/12/31      0:14            215 .gitconfig
-a----        2024/12/26     19:03             20 .lesshst
-a----        2024/12/26     19:53             64 .python_history

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# .pyenv 文件夹下的内容
PS C:\Users\rolfz\.pyenv> ls


    目录: C:\Users\rolfz\.pyenv


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        2024/12/19     19:42                .github
d-----        2024/12/19     19:42                docs
d-----        2024/12/19     19:48                pyenv-win
d-----        2024/12/19     19:42                tests
-a----        2024/12/19     19:42             19 .coveralls.yml
-a----        2024/12/19     19:42           1422 .gitignore
-a----        2024/12/19     19:42              7 .version
-a----        2024/12/19     19:42           1096 LICENSE
-a----        2024/12/19     19:42            134 mirrors.txt
-a----        2024/12/19     19:42          10636 README.md
-a----        2024/12/19     19:42              0 requirements.txt
-a----        2024/12/19     19:42             98 requirements_dev.txt
-a----        2024/12/19     19:42           2148 setup.py
-a----        2024/12/19     19:42             29 _config.yml

如果你能看见 .pyenv 文件夹，其内容类似于这里展示的，那么可以认为安装已经成功了，但这时还不能在终端中使用 pyenv 命令安装 Python。我们还得添加一些有关的 Windows OS 的环境变量。

配置环境变量：可以借助于官方提供的命令实现。

1
2
3
4
5


[System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")

[System.Environment]::SetEnvironmentVariable('PYENV_ROOT',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")

[System.Environment]::SetEnvironmentVariable('PYENV_HOME',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")

以上命令也是在终端中执行。实现的功能就是在 Windows OS 中添加三个分别名为 PYENV，PYENV_ROOT，PYENV_HOME 的三个环境变量，且其值分别为$HOME\.pyenv\pyenv-win\， $HOME\.pyenv\pyenv-win\， $HOME\.pyenv\pyenv-win\。这也意味着，我们可以手动将其添加到系统的环境变量中。如果打开系统的环境变量的设置界面，就可以看见类似于如图所示的内容：

到此为止，我们还不能在终端中使用 pyenv 命令来安装 Python。还需要最后将该命令的路径添加到系统的路径中。请参阅第4布。

在用户路径中添加 pyenv 命令的路径：同上，可以借助于官方提供的命令实现。

1

[System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")

执行完以上命令后，在系统配置环境变量的界面中的Path变量中可以看见增加了两条，分别为：$HOME\.pyenv\pyenv-win\bin, $HOME\.pyenv\pyenv-win\shims。如上图所示。

重启终端：关闭并重新打开终端以应用以上更改。
验证安装：在重新打开的终端中运行以下命令。如果安装成功，将显示 pyenv 版本。
1

pyenv --version # 返回 pyenv 3.1.1

由于网络原因，建议将以下变量添加到系统或者用户的环境变量中：

PYTHON_BUILD_MIRROR_URL 为国内镜像站点，如 https://mirrors.huaweicloud.com/python/。
同时设置PYTHON_BUILD_MIRROR_URL_SKIP_CHECKSUM 的值为1
设置完这两个环境变量后，为了使其生效，同样需要重启终端。
NOTE：需要在重启后的终端中执行 pyenv update，更新 pyenv的索引（这个过程需要些时间）。当然，如果您在终端中执行该命令后，能看见类似于如下所示的显示，证明国内镜像站点设置成功，否则，需要检查环境变量的设置。

1
2
3


PS C:\Users\rolfz> pyenv update
:: [Info] ::  Mirror: https://mirrors.huaweicloud.com/python/
:: [Info] ::  Scanned 225 pages and found 746 installers.

关于在 Windows OS 中安装 pyenv-win 到此就结束了。下节将简单介绍如何使用 pyenv 管理 Python 版本，同时也建议参考官方教程，或者在终端中执行 pyenv help 命令。该命令会显示出 pyenv 所支持的所有功能。如下所示：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


PS C:\Users\rolfz> pyenv help  # <---执行的命令
Usage: pyenv <command> [<args>]

Some useful pyenv commands are:
   commands    List all available pyenv commands
   local       Set or show the local application-specific Python version
   latest      Print the latest installed or known version with the given prefix
   global      Set or show the global Python version
   shell       Set or show the shell-specific Python version
   install     Install a Python version using python-build
   uninstall   Uninstall a specific Python version
   rehash      Rehash pyenv shims (run this after installing executables
   version     Show the current Python version and its origin
   versions    List all Python versions available to pyenv
   which       Display the full path to an executable
   whence      List all Python versions that contain the given executable

See `pyenv help <command>' for information on a specific command.
For full documentation, see: https://github.com/pyenv-win/pyenv-win#readme

使用 pyenv-win

基本用法说明

从前面的介绍可知，执行 pyenv help 命令可以查看 pyenv 的基本用法。输出的结果包括了 pyenv 支持的一系列子命令，其格式为 pyenv <command> [<args>]。其中 pyenv 是主命令；<command> 表示子命令，是您希望 pyenv 执行的具体操作。例如，help, install、global、local 等。这部分需要您根据需求指定。[<args>] 表示可选参数或参数列表（args 是 “arguments” 的缩写）。参数是传递给子命令的额外信息，用于具体化或补充命令的执行。例如，当您运行 pyenv install <version> 时，<version> 就是参数，表示需要安装的具体 Python 版本。

命令行工具通常有以下约定：

方括号 [ ] 表示内容是可选的，即某些命令可能不需要额外的参数。例如：pyenv versions 这条命令无需参数，直接列出已安装的 Python 版本。
如果参数没有方括号，表示是必需的，命令无法省略。例如：pyenv install <version>, 这里的 <version> 就是必需的，必须指定要安装的具体 Python 版本。
尖括号 < > 中的内容表示占位符，是你需要根据实际情况替换的部分。例如：pyenv install 3.13.1。其中 3.13.1 就是占位符 <version> 的具体替代内容。

常用命令

这里仅介绍个人使用平频率比较高的命令。其他的请参考官方说明。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


   commands    # 列出所有可用的 pyenv 子命令：
   local       # 设置或查看本地应用程序的特定 Python 版本
   latest      # 输出符合给定前缀的已安装或已知的最新 Python 版本
   global      # 设置或查看全局 Python 版本（适用于 OS 范围）
   shell       # 设置或查看当前 shell 的 Python 版本（仅限当前终端会话）：
   install     # 安装指定版本的 Python
   uninstall   # 卸载特定版本的 Python：
   rehash      # 重新生成 pyenv 的 shims（运行此命令以更新新安装的可执行文件）
   version     # 查看当前正在使用的 Python 版本及其来源（global/local/shell）
   versions    # 列出系统中所有通过 pyenv 管理的 Python 版本（包括全局、本地和 shell 的版本）
   which       # 显示当前使用的 Python 可执行文件的完整路径：
   whence      # 列出所有包含指定可执行文件的 Python 版本

可能值得说明的是 rehash 子命令。按照官方说明，在使用 pip 安装或卸载任何库，或者修改某个 Python 版本文件夹中的文件后，咱们必须运行 pyenv rehash 命令来更新 pyenv 的 shims。并且该命令必须在 .pyenv 文件夹之外运行，不能在 .pyenv 文件夹内部执行。这是什么意思呢？

比如说，我们通过 pip install black 安装了一个新的 black 库，按照以上说明，我们就应该执行 pyenv rehash，以此保证这些新安装的可执行文件可以正常使用。如果此时不运行 pyenv rehash，那么，我们可能会遇到以下问题：

新安装的可执行文件无法被识别或使用。比如说前面安装的 black 库的可执行文件就不会被添加到 pyenv 的 shims 中。结果就是在终端中运行这些命令时，可能会提示如下错误：
1

black: command not found
旧版本的可执行文件被错误使用：比如，卸载了某些库或更新了它们的版本（如通过 pip uninstall 或 pip install --upgrade），但没有运行 pyenv rehash，pyenv 的 shims 可能仍然指向旧的文件路径。这会导致卸载的工具仍然可以运行（虽然它实际上已经被删除），该工具版本就不是刚刚更新的最新版本。
环境不一致：这个和第二个问题类似，因为 pyenv 通过 shims 管理不同 Python 版本及其相关的库和工具。如果没有运行 pyenv rehash，新添加或删除的库可能不会正确应用到当前的环境中，导致环境中的库和工具与实际的 Python 安装内容不一致。

最后，巧妙应用 pyenv help [<command>] 可以解决大多数 pyenv 的使用方法问题。

安装 Poetry

在终端中运行官方提供的安装脚本：

1

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

值得说明的是，官方提供的原始安装脚本为：

1

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

唯一的区别是我将最后面的 py 改为了 python。这里的 py 或者修改后的 python 指的是在系统终端中能运行的 python 命令（在终端中执行该命令，正常情况下应该能进入 Python 的解释器里，如下图所示）。

由于前面我使用了 pyenv 来安装和管理系统的 Python 版本，通常情况下，在终端中能够执行的，启动 Python 的解释器的命令为 python，而非 py。

配置环境变量（如果安装脚本未自动完成）：这一步很重要，按照最新的安装脚本，通常会在执行完 Poetry 的安装后，会提示将 Poetry 的安装路径添加到系统的环境变量中。请一定仔细阅读出现的提示。通常，Poetry 会被安装在 C:\Users\用户名\AppData\Roaming\Python\Scripts 或 C:\Users\用户名\.poetry\bin。根据提示，执行相关命令，或者将 Poetry 的安装路径手动添加到用户的 Path 环境变量中。比如我的系统的环境变量如下（用红框标记的有关 Poetry 内容）：

验证安装：重新打开 PowerShell 并运行以下命令来验证 Poetry 安装成功：
1

poetry --version # 返回类似 Poetry (version 1.8.5) 表示已安装成功

使用 Poetry 管理项目依赖

关于 poetry 的使用，同样建议参考官方文档。可能值得说明的是，可以设置 poetry 的 in-project 配置项值为 true，使其在创建新的项目环境时，将其置于项目文件夹中。具体命令如下：

1

poetry config virtualenvs.in-project true # 默认该 config 的值为 false

同 pyenv，巧妙应用 poetry [help] [<command>] 可以解决大多数 poetry 的使用方法问题。