VLXI-Cookiecutter-Python

Poetry Quick Reference

Authors
Kevin T. Chu <kevin@velexi.com>

Version: 2024-06-13

Poetry is a useful Python package and dependency management tool. It also provides support for managing Python environments, building and packaging Python projects, and publishing Python packages.

Managing Project Dependencies

Display the list of Python package dependencies.
```
$ poetry show
```
Add a Python package dependency.
```
$ poetry add PKG_NAME
```
Remove a Python package dependency.
```
$ poetry remove PKG_NAME
```
Install the package dependencies included in pyproject.toml.
```
$ poetry install
```
Update the package dependencies to the latest available versions.
```
$ poetry update
```
Note. This to equivalent to deleting the poetry.lock file and running poetry install.

Managing Virtual Environments

Basic Commands

All of the following commands operate on the Python virtual environments for a specific project defined by a pyproject.toml file. They all require that a pyproject.toml file exists in the current directory or an ancestor of the current directory.

Activate or create a virtual environment using one of the following command variations.
- Use a specific Python executable for the virtual environment.
```
$ poetry env use /full/path/to/python
```
- Use a Python executable on your PATH for the virtual environment. For instance,
```
$ poetry env use python3.11
```
  or
```
$ poetry env use 3.11
```
Deactivate a virtual environment.
```
$ poetry env use system
```
Display information about the virtual environment.
```
$ poetry env info
```
Delete a virtual environment using one of the following command variations.
```
$ poetry env remove /full/path/to/python
$ poetry env remove python3.11
$ poetry env remove 3.11
$ poetry env remove package-name-12345678-py3.11
```
The full environment name in the last variation is available in the output of the poetry env info command.

Configuration

In-Project Virtual Environments. By default, poetry stores Python virtual environments in a (user-level) central location. However, we recommend configuring poetry to use an in-project virtual environment for ease of maintenance (e.g. deleting the entire project directory automatically deletes the Python virtual environment).
- To configure poetry to use in-project virtual environments for all projects, use
```
$ poetry config virtualenvs.in-project true
```
- To configure poetry to use in-project virtual environments locally within a specific projects, use
```
$ poetry config --local virtualenvs.in-project true
```
  This command will create a poetry.toml file that can be added to the project code repository.

References

Poetry Docs: Managing environments

This site is open source. Improve this page.