Managing dependencies in Python projects can be challenging, especially when dealing with version conflicts, virtual environments, and deployment requirements. Poetry is a modern dependency management tool that simplifies packaging, virtual environment handling, and publishing. In this guide, we’ll explore how to effectively manage Python project dependencies using Poetry.

Why Use Poetry Over Pip and Virtualenv?

Python developers traditionally use pip and virtualenv for dependency management, but Poetry provides a more efficient solution with features like:

  • Simplified dependency management: Uses pyproject.toml for clear package definitions.
  • Automatic virtual environments: Isolates dependencies seamlessly.
  • Dependency resolution: Ensures compatibility with all installed packages.
  • Publishing support: Easily publish packages to PyPI.

Let’s dive into how to use Poetry for your Python projects.

Installing Poetry

To install Poetry, use the official installer:

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

Verify the installation:

poetry --version

Setting Up a New Python Project with Poetry

To create a new project:

poetry new my_project  
cd my_project

This command generates a structured project with the following files:

  • pyproject.toml – Defines dependencies and project metadata.
  • poetry.lock – Ensures reproducible installations.
  • README.md, tests/ – Default setup for documentation and testing.

If you already have a project, initialize Poetry inside it:

poetry init

Follow the prompts to configure dependencies.

Adding and Managing Dependencies

Adding a Dependency

To add a package:

poetry add requests

To add a development dependency (for testing, linting, etc.):

poetry add --dev pytest
Removing a Dependency
poetry remove requests
Viewing Installed Dependencies
poetry show

Managing Virtual Environments

Poetry automatically creates a virtual environment for each project.

Checking the Virtual Environment Path
poetry env info
Activating the Virtual Environment

To activate it manually:

source $(poetry env info --path)/bin/activate
Deactivating the Virtual Environment

Simply run:

deactivate

To remove an existing environment:

poetry env remove python

Using Poetry to Run and Manage Scripts

Instead of manually activating the virtual environment, use poetry run:

poetry run python script.py

For interactive mode:

poetry shell

This ensures that commands run within the Poetry-managed environment.

Locking and Resolving Dependencies

To install dependencies from pyproject.toml and ensure consistency:

poetry install

To update dependencies while maintaining compatibility:

poetry update

For specific packages:

poetry update requests

Publishing Python Packages with Poetry

Building the Package
poetry build
Publishing to PyPI
poetry publish --username your_username --password your_password

For automated publishing, set up credentials:

poetry config pypi-token.pypi your_token

Best Practices for Managing Dependencies with Poetry

  1. Pin exact versions for production stability 
    requests = "2.28.1"
  2. Use development dependencies for testing and linting 
    poetry add --dev black pytest
  3. Regularly update dependencies while testing for regressions 
    poetry update

  4. Store poetry.lock in version control for reproducibility

  5. Use Poetry’s virtual environments instead of global Python installs

Conclusion

Poetry streamlines dependency management, virtual environments, and package publishing in Python. By adopting Poetry, developers can simplify project setup, improve maintainability, and ensure reproducibility.

Ready to level up your Python dependency management? Try Poetry today! 🚀