poetry：windows11下环境管理工具的安装使用

作者：好邻居发布时间：2024-09-10 14:46:46

阅读： 123

正文

中文教程

https://docs.dify.ai/v/zh-hans/getting-started/install-self-hosted/local-source-code

在以后的环境中，（有poetry.lock poetry.toml pyproject.toml README.md文件）

E:\aiagent\dify\api>poetry env use C:\Users\Administrator\AppData\Local\Programs\Python\Python310\python.exe

E:\aiagent\dify\api>poetry install

基础环境

系统版本	python版本	poetry版本
win11 23H2	多版本 + 3.6.8(默认) + 3.8.6 + 3.10.4	1.8.2

安装

https://python-poetry.org/docs/

我们选择脚本的方式安装

使用powershell安装

安装命令

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

注意：
这里需要特别提醒，如果默认的python环境是3.6的话，会报错，无法找到portry的包，就无法安装
因为我这里是多python版本，所以，遇到这个问题堵了我好久
解决方法就是到python3.10的安装目录下，然后右键打开powershell
然后再运行命令 (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | .\python.exe -
就可以正常安装了

过程

Retrieving Poetry metadata# Welcome to Poetry!This will download and install the latest version of Poetry,a dependency and package manager for Python.It will add the `poetry` command to Poetry's bin directory, located at:C:\Users\xxx\AppData\Roaming\Python\ScriptsYou can uninstall at any time by executing this script with the --uninstall option,and these changes will be reverted.Installing Poetry (1.8.2)Installing Poetry (1.8.2): Creating environmentInstalling Poetry (1.8.2): Installing PoetryInstalling Poetry (1.8.2): Creating scriptInstalling Poetry (1.8.2): DonePoetry (1.8.2) is installed now. Great!You can test that everything is set up by executing:`poetry --version`

查看版本

poetry --versionPoetry (version 1.8.2)

这就表明安装成功

版本升级

poetry self update

升级预安装版本

poetry self update --preview

升级特定版本

poetry self update 1.2.0

1.1 版本的poetry无法原地更新到 1.2 或更新的版本。
要迁移到更新的版本，请使用您原来的安装方法卸载，然后使用上述方法重新安装。

卸载poetry

curl -sSL https://install.python-poetry.org | ./python - --uninstall

同样需要到安装poetry的python安装目录下运行

显示如下则表示卸载成功

Removing Poetry (1.8.2)

使用

https://python-poetry.org/docs/cli/

项目创建

poetry new my-package

会帮忙生成基础文件

my-package├── pyproject.toml├── README.md├── my_package│   └── __init__.py└── tests    └── __init__.py

如果你想给你的项目命名一个与文件夹不同的名字，你可以传递 --name 选项：

poetry new my-folder --name my-package

这种方法我们用的少，因为其实很多时候我们只需要 pyproject.toml 文件

所以，这里就需要用到init方法了

项目初始化

手动创建项目目录

mkdir my-packagecd my-package

初始化项目

poetry initThis command will guide you through creating your pyproject.toml config.Package name [my-package]:Version [0.1.0]:Description []:Author [xxxx <xxxxx@163.com>, n to skip]:License []:Compatible Python versions [^3.10]:Would you like to define your main dependencies interactively? (yes/no) [yes]You can specify a package in the following forms:  - A single name (requests): this will search for matches on PyPI  - A name and a constraint (requests@^2.23.0)  - A git url (git+https://github.com/python-poetry/poetry.git)  - A git url with a revision (git+https://github.com/python-poetry/poetry.git#develop)  - A file path (../my-package/my-package.whl)  - A directory (../my-package/)  - A url (https://example.com/packages/my-package-0.1.0.tar.gz)Package to add or search for (leave blank to skip):Would you like to define your development dependencies interactively? (yes/no) [yes]Package to add or search for (leave blank to skip):Generated file[tool.poetry]name = "my-package"version = "0.1.0"description = ""authors = ["xxxx <xxxxx@163.com>"]readme = "README.md"[tool.poetry.dependencies]python = "^3.10"[build-system]requires = ["poetry-core"]build-backend = "poetry.core.masonry.api"Do you confirm generation? (yes/no) [yes]

初始化安装

poetry installUpdating dependenciesResolving dependencies... (0.1s)Writing lock fileInstalling the current project: my-package (0.1.0)Warning: The current project could not be installed: [Errno 2] No such file or directory: 'C:\\my-package\\README.md'If you do not want to install the current project use --no-root.If you want to use Poetry only for dependency management but not for packaging, you can disable package mode by setting package-mode = false in your pyproject.toml file.In a future version of Poetry this warning will become an error!

上面的提示是当执行 poetry install 命令时，默认情况下Poetry会将当前目录下的项目视为一个可安装的Python包，并尝试构建和安装它。
在这个过程中，它通常会包括项目的根目录下的必要文件，如 README.md、LICENSE 等。
解决办法：
如果你并不希望安装当前项目本身，而只想安装该项目的依赖项，可以在命令后面加上 --no-root 参数: poetry install --no-root
如果你确实需要安装项目，但当前缺失了 README.md 文件，可以手动创建。
若你的意图只是使用Poetry进行依赖管理而不打包项目，可以在 pyproject.toml 文件中设置 package-mode = false 来禁用包模式。
不过请注意，这样做后Poetry将不再把当前项目当作一个可发布的包来对待，可能会影响到诸如构建、发布等操作。

全局选项

--verbose (-v|vv|vvv): "-v" 正常输出, "-vv" 详细输出 "-vvv" debug
--help (-h) : 帮助信息
--quiet (-q) : 不输出任何信息
--ansi: 强制 ANSI 输出
--no-ansi: 禁止ANSI 输出
--version (-V): 显示版本
--no-interaction (-n): 禁止交互询问

安装第三方库

poetry add requests==xxx

--group (-D): 分组
--editable (-e): 添加到编辑模式
--extras (-E): 添加额外的依赖
--optional: 添加至可选依赖
--python: 指定python版本
--platform: 指定操作系统
--source: 使用源名称安装
--allow-prereleases: 接受 prereleases 安装
--dry-run: 输出操作但不执行
--lock: 只更新锁定不安装
--dev：指定为开发依赖

移除第三方库

poetry remove xxx

--group (-D): 分组
--dry-run: 输出操作但不执行

列出所有可安装的包

poetry show 
asgiref           3.7.2  ASGI specs, helper code, and adaptersbeautifulsoup4    4.12.3 Screen-scraping librarybs4               0.0.2  Dummy package for Beautiful Soup (beautifulsoup4)django            5.0.3  A high-level Python web framework that encourages rapid development and clean, pragmatic design.mysqlclient       2.2.4  Python interface to MySQLsoupsieve         2.5    A modern CSS selector implementation for Beautiful Soup.sqlparse          0.4.4  A non-validating SQL parser.typing-extensions 4.10.0 Backported and Experimental Type Hints for Python 3.8+tzdata            2024.1 Provider of IANA time zone data

--without: 忽略依赖
--with: 同时显示
--only: 只显示指定的依赖
--default: 只显示默认的
--no-dev: 不显示开发的依赖
--tree: 以树状形式显示
--latest (-l): 展示最新的版本
--outdated (-o): 显示最新版本，但仅适用于过时的软件包

常用
--tree

poetry show --tree   bs4 0.0.2 Dummy package for Beautiful Soup (beautifulsoup4)└── beautifulsoup4 *    └── soupsieve >1.2django 5.0.3 A high-level Python web framework that encourages rapid development and clean, pragmatic design.├── asgiref >=3.7.0,<4│   └── typing-extensions >=4├── sqlparse >=0.3.1└── tzdata *mysqlclient 2.2.4 Python interface to MySQL

读取 `pyproject.toml` 并安装相关依赖

# 需要进入pyproject.toml所在目录poetry install

--without: 忽略依赖
--with: 安装可选的依赖
--only: 只安装指定的依赖
--default: 只安装默认的依赖
--sync: 同步锁定的版本至环境中
--no-root: 不安装根依赖包
--dry-run: 输出操作但不执行
--extras (-E): 安装额外的包

创建虚拟环境

poetry env use /full/path/to/python

在 poetry install 之前，可以切换任意版本的python，也就是用你所指定的python版本来创建虚拟环境

激活虚拟环境

# 需要进入pyproject.toml所在目录
E:\aiagent\poetrytest>poetry shell
会进入虚拟环境，以前的命令行会丢失，退出回不去
Spawning shell within C:\Users\xxx\AppData\Local\pypoetry\Cache\virtualenvs\abc-yLlOvVWf-py3.10PowerShell 7.4.1(abc-py3.10) PS E:\xxxxx\xxx\xxxx>

在当前项目下创建虚拟环境

我们可以使用 poetry config --list 指令来查看 poetry 的几个主要设定，

X:\poetry-demo>poetry config --list

cache-dir = "C:\\Users\\xxp\\AppData\\Local\\pypoetry\\Cache"

experimental.new-installer = true

experimental.system-git-client = false

installer.max-workers = null

installer.modern-installation = true

installer.no-binary = null

installer.parallel = true

virtualenvs.create = true

virtualenvs.in-project = null

virtualenvs.options.always-copy = false

virtualenvs.options.no-pip = false

virtualenvs.options.no-setuptools = false

virtualenvs.options.system-site-packages = false

virtualenvs.path = "C:\\Users\\xxp\\AppData\\Local\\pypoetry\\Cache\\virtualenvs"

virtualenvs.prefer-active-python = false

virtualenvs.prompt = "{project_name}-py{python_version}"

其中 virtualenvs.create = true 若改为 false，则可以停止 poetry 在检查不到虚拟环境是自动创建的行为模式，但是建议不要改动。

而 virtualenvs.in-project = false 就是我们要修改的目标，使用指令：

poetry config virtualenvs.in-project true

先把之前创建的虚拟环境删除

X:\poetry-demo>E:\aiagent\poetrytest>poetry env remove C:\Users\Administrator\AppData\Local\pypoetry\Cache\virtualenvs\test-ilgYFyu4-py3.10\Scripts\python.exe

Deleted virtualenv: C:\Users\xxp\AppData\Local\pypoetry\Cache\virtualenvs\poetry-demo-Ut74gzEx-py3.10

重新创建虚拟环境，看一下差异

进入虚拟环境，就可以直接执行各种python命令

退出虚拟环境

exit

不需要进入虚拟环境的情况下，在虚拟环境中执行命令

只需要在命令前面添加 poetry run

poetry run xxx

查看虚拟环境信息

E:\aiagent\poetrytest>poetry env info

Virtualenv
Python:         3.10.11
Implementation: CPython
Path:           E:\aiagent\poetrytest\.venv
Executable:     E:\aiagent\poetrytest\.venv\Scripts\python.exe
Valid:          True

Base
Platform:   win32
OS:         nt
Python:     3.10.11
Path:       C:\Users\Administrator\AppData\Local\Programs\Python\Python310
Executable: C:\Users\Administrator\AppData\Local\Programs\Python\Python310\python.exe

会显示出虚拟环境的相关信息

查看虚拟环境列表

E:\aiagent\poetrytest>poetry env list
.venv (Activated)
E:\aiagent\poetrytest>poetry env list
abc-yLlOvVWf-py3.10(Activated)

删除虚拟环境

poetry env remove abc-yLlOvVWf-py3.10

E:\aiagent\poetrytest>poetry env remove C:\Users\Administrator\AppData\Local\pypoetry\Cache\virtualenvs\test-ilgYFyu4-py3.10\Scripts\python.exe

搜索远程包

poetry search xxx

锁定版本

poetry lock

对环境进行更新

poetry update

导出锁定的文件为其他的格式

poetry export -f requirements.txt --output requirements.txt

--format (-f): 转换的格式，暂时只支持requirements.txt
--output (-o): 输出文件名字
--dev: 包括开发的依赖
--extras (-E): 额外的依赖
--without-hashes: 忽略哈希
--with-credentials: 包括合格证书

修改仓库源

[[tool.poetry.source]]name = "douban"url = "https://pypi.doubanio.com/simple/"

poetry 指令

poetry 是一个独立的命令行工具，他有自己的指令，需要花费额外的时间与精力学习，相较 pip 更加复杂，这个能是使用 poetry 的一道关卡。好在常用指令其实不超过 10 个，下面就来一一介绍。

安装模块

使用指令

shell

poetry add

相较于 pip install，我们试试安装 flask 看看会有什么样的变化

(poetry-demo-py3.10) X:\poetry-demo>poetry add flask

Using version ^2.3.2 for flask

Updating dependencies

Resolving dependencies...

Writing lock file

Package operations: 8 installs, 0 updates, 0 removals

• Installing colorama (0.4.6)

• Installing markupsafe (2.1.3)

• Installing blinker (1.6.2)

• Installing click (8.1.6)

• Installing itsdangerous (2.1.2)

• Installing jinja2 (3.1.2)

• Installing werkzeug (2.3.6)

可以看到 poetry 会将所有的信息全部列出来，并且清楚的告知了新增了那些第三方模块。

此时项目中的 pyproject.toml 也发生了变化

[tool.poetry.dependencies]

python = "^3.10"

flask = "^2.3.2" # 新增部分

这里要说明，安装 flask ，则 pyproject.toml 只会新增 flask = "^2.3.2" 这个字段的第三方模块，其余依赖不会出现在 toml 文件中。

这里是一个非常大的优点，以便区分那些是用户安装的第三方模块，那些是第三方模块一并安装的依赖。

poetry.lock 与更新顺序

除了更新 pyproject.toml ，此时项目中还会新增一个文件，名为 poetry.lock ，它实际上就相当于 pip 的 requirements.txt ，详细记录了所有安装的模块与版本。

当使用 poetry add 指令时，poetry 会自动依序帮你做完这三件事：

更新 pyproject.toml。

依照 pyproject.toml 的内容，更新 poetry.lock 。

依照 poetry.lock 的内容，更新虚拟环境。

由此可见， poetry.lock 的内容是取决于 pyproject.toml ，但两者并不会自己连动，一定要基于特定指令才会进行同步与更新， poetry add 就是一个典型案例。

此时项目目录结构如下：

poetry-demo

├── poetry.lock

└── pyproject.toml

0 directories, 2 files

poetry lock ：更新 poetry.lock

当你自行修改了 pyproject.toml 内容，比如变更特定模块的版本（这是有可能的，尤其在手动处理版本冲突的时候），此时 poetry.lock 的内容与 pyproject.toml 出现了脱钩，必须让它依照新的 pyproject.toml 内容更新、同步，使用指令：

poetry lock

如此一来，才能确保手动修改的内容，也更新到 poetry.lock 中，毕竟虚拟环境如果要重新建立，是基于 poetry.lock 的内容来安装模块，而非 pyproject.toml 。

还是那句话：

poetry.lock 相当于 Poetry 的 requirements.txt 。

但要特别注意的是， poetry lock 指令，仅会更新 poetry.lock ，不会同时安装模块至虚拟环境

因此，在执行完 poetry lock 指令后，必须再使用 poetry install 来安装模块。否则就会出现 poetry.lock 和虚拟环境不一致的状况。

更多 poetry lock 细节可参考官方文件，其中特别值得注意的是 --no-update 参数。

新增模块至 dev-dependencies

有些模块，比如 pytest 、 black 等等，只会在开发环境中使用，产品的部署环境并不需要。

Poetry 允许你区分这两者，将上述的模块安装至 dev-dependencies 区块，方便让你轻松建立一份「不包含」 dev-dependencies 开发模块的安装清单。

在此以 Black 为例，安装方式如下：

poetry add black --group dev

结果的区别显示在 pyproject.toml 里：

[tool.poetry.dependencies]

python = "^3.10"

flask = "^2.3.2"

[tool.poetry.group.dev.dependencies]

black = "^23.7.0"

可以看到 black 被列在不同区块： tool.poetry.dev-dependencies 。

强烈建议善用 dev-dependencies

善用 --group dev 参数，明确区分开发环境，我认为非常必要。

首先，这些模块常常属于「检测型」工具，相关的依赖模块着实不少！比如 flake8 ，它依赖了 pycodestyle 、 pyflakes 、 mccabe 等等，还有 black 、 pre-commit ，依赖模块数量也都很可观。

Poetry 更新模块

这个就很简单了，使用 poetry update 指令即可：

poetry update

上面指令会更新全部可能可以更新的模块，也可以仅指定特定模块，比如：

poetry update requests toml

关于 poetry update 的其余参数，请参考文件。

还一件重要的事，那就是关于模块版本的升级限制规则，取决于你在 pyproject.toml 中的设定。

列出全部模块清单

类似 pip list ，这里要使用 poetry show

特别提醒的是，这里的清单内容并不是来自于虚拟环境，这点和 pip 不同，而是来自于 poetry.lock 的内容。

你可能会想，来自于 poetry.lock 或虚拟环境，有差吗？两者不是应该要一致？

没错，理论上是，但也有不一致的时候，比如你使用了 pip install 指令安装模块，就不会记载在 poetry.lock 中，那 poetry show 自然也不会显示。

树状显示模块依赖层级

poetry show --tree

让主要模块与其依赖模块的关系与层次，一目了然。

而且很贴心的是，它也可以只显示指定模块的依赖层级，以 celery 为例：

poetry show celery --tree

Poetry 移除模块

使用 poetry remove 指令。和 poetry add 一样，可以加上 -D 参数来移除置于开发区的模块。

而移除模块时的依赖解析能力，正是 Poetry 远优于 pip 的主要环节，因为 pip 没有嘛！也是我提议改用 Poetry 的关键理由——为了顺利移除模块与依赖。

前面已经提过，pip 的 pip uninstall 只会移除你所指定的模块，而不会连同依赖模块一起移除。

这是基于安全考量，因为 pip 没有依赖解析功能。如果贸然移除所有安装时一并安装的依赖模块，可能会造成巨大灾难，让别的模块失去效用。

所以，使用 pip 时，我们鲜少会去移除已经不再使用的模块。毕竟依赖关系错综复杂，移除模块可能造成许多副作用，实在是太麻烦了。

poetry remove 的依赖解析

poetry remove flask

输出 Poetry 虚拟环境的 requirements.txt

理论上，全面改用 Poetry 后，项目中是不需要存在 requirements.txt ，因为它的角色已经完全被 poetry.lock 所取代。

但事实是，你可能还是需要它，甚至希望它随着 poetry.lock 的内容更新！至少对我而言就是如此，我在 Docker 部署环境中并不使用 Poetry，所以我需要一份完全等价于 poetry.lock 的 requirements.txt ，用于 Docker 部署。

你可能想说，那我就在 Poetry 的虚拟环境下，使用以往熟悉的指令 pip freeze > requirements.txt 来产生一份就可以了吧？我本来也是这么想，但实际的产出却是如此：（提醒：目前 poetry-demo 专案中仅剩下 Black 和它的依赖模块）

black @ file:///Users/kyo/Library/Caches/pypoetry/artifacts/11/4c/fc/cd6d885e9f5be135b161e365b11312cff5920d7574c8446833d7a9b1a3/black-22.3.0-cp38-cp38-macosx_10_9_x86_64.whl

click @ file:///Users/kyo/Library/Caches/pypoetry/artifacts/f0/23/09/b13d61d1fa8b3cd7c26f67505638d55002e7105849de4c4432c28e1c0d/click-8.1.2-py3-none-any.whl

mypy-extensions @ file:///Users/kyo/Library/Caches/pypoetry/artifacts/b6/a0/b0/a5dc9acd6fd12aba308634f21bb7cf0571448f20848797d7ecb327aa12/mypy_extensions-0.4.3-py2.py3-none-any.whl

...

这呈现好像不是我们以前熟悉的那样：

black==22.3.0

click==8.1.2

...

没错，只要是使用 poetry add 安装的模块，在 pip freeze 就会变成这样。此时想输出类似 requirements.txt 的格式，需要使用 poetry export 。

poetry export -f requirements.txt -o requirements.txt --without-hashes

我们再看一下输出结果，虽然不尽相同，但也相去不远了……吗？等等，怎么是空白？

输出 dev-dependencies

因为 poetry export 预设只会输出 toml 中的 [tool.poetry.dependencies] 区块的模块！还记得上面我们把 Black 安装到 [tool.poetry.dev-dependencies] 了吗？

这倒是没错，不过基于演示需求，我们必须输出 [tool.poetry.dev-dependencies] 的模块，才能看到 Black。

加上 --dev 参数即可：

poetry export -f requirements.txt -o requirements.txt --without-hashes --dev

输出的 requirements.txt 内容：

black==22.3.0; python_full_version >= "3.6.2"

click==8.1.2; python_version >= "3.7" and python_full_version >= "3.6.2"

colorama==0.4.4; python_version >= "3.7" and python_full_version >= "3.6.2" and platform_system == "Windows"

...

虽然长得有点不一样，但这个档案确实是可以 pip install 的。

从这里也可以看出先前一再提及区分开发、部署依赖的价值——大部分时候我们并不需要输出开发用模块。

poetry export 所有参数用法与说明，请参考文件。

Poetry 常用指令清单

算来算去，Poetry 的常用指令主要有下面几个：

poetry add

poetry remove

poetry export

poetry env use

poetry shell

poetry show

poetry init

poetry install

其中一半，单一项目可能只会用个一两次而已，比如 init 、 install 和 env use ，实际上需要学习的指令并不多。

修改 poetry 镜像源

修改为清华镜像源