Poetry is a powerful dependency management and packaging tool for Python. It provides a seamless workflow for managing dependencies, creating virtual environments, and packaging applications. This guide will walk you through the essential features of Poetry, including how to generate a requirements.txt file for compatibility with pip.

1. Installing Poetry

To install Poetry, run the following command:

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

After installation, ensure Poetry is available in your terminal by checking its version:

poetry --version

If the command does not work, add Poetry to your PATH:

export PATH="$HOME/.local/bin:$PATH"

2. Creating a New Poetry Project

To create a new Python project with Poetry, use:

poetry new my_project

This command sets up a basic Python package structure:

my_project/
├── pyproject.toml  # Configuration file for Poetry
├── README.rst
├── my_project/     # Project source code
│   └── __init__.py
└── tests/          # Test files

If you already have a project and want to initialize Poetry within it, navigate to the project directory and run:

poetry init

This will guide you through setting up pyproject.toml interactively.

3. Managing Dependencies

Adding Dependencies

To install a package and automatically update pyproject.toml and poetry.lock, use:

poetry add requests

For a development-only dependency:

poetry add --dev pytest

Removing Dependencies

To remove a package:

poetry remove requests

Updating Dependencies

To update all dependencies:

poetry update

To update a specific package:

poetry update requests

4. Virtual Environments and Running Code

Poetry automatically manages a virtual environment for your project. You can activate it with:

poetry shell

To run a Python script within the virtual environment without activating the shell:

poetry run python script.py

To check the virtual environment being used:

poetry env info

5. Exporting Requirements for pip

Poetry does not use requirements.txt natively, but you can export dependencies for environments that require it (e.g., Docker, CI/CD pipelines).

6. Install the Poetry Export Plugin

Poetry 2.0+ requires an additional plugin to export dependencies:

poetry self add poetry-plugin-export

7. Generate requirements.txt

Run the following command to export dependencies:

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

If you need to include development dependencies:

poetry export -f requirements.txt --output requirements.txt --without-hashes --with dev

You can then install these dependencies using pip:

pip install -r requirements.txt

8. Version Management

To check the current project version:

poetry version

To update the version:

poetry version patch  # Increases 1.0.0 -> 1.0.1
poetry version minor  # Increases 1.0.0 -> 1.1.0
poetry version major  # Increases 1.0.0 -> 2.0.0

9. Publishing to PyPI

To publish your package to PyPI, first build it:

poetry build

Then publish it:

poetry publish

To publish to TestPyPI for testing:

poetry publish --repository testpypi

Conclusion

Poetry simplifies dependency management, virtual environments, and packaging for Python projects. By using Poetry, you can ensure a more reliable and consistent development workflow. With the ability to export requirements.txt, Poetry remains compatible with traditional Python workflows while providing a modern alternative to pip and virtualenv.

Start using Poetry today to streamline your Python project management! 🚀