Python Poetry Guide for Beginners

Poetry is a dependency management and packaging tool for Python. It helps developers manage project dependencies, publish packages, and configure virtual environments consistently and reliably.

Python Poetry replaces tools like pip, virtualenv, and setuptools to streamline software development from project creation to deployment.

This guide explains what Python Poetry is, how to install it, how to use it, and the best practices.

Prerequisites

• Python 3 installed. (Check out our guides on how to install Python on Windows and Ubuntu)
• Access to the command line/terminal.
• cURL installed or a similar tool.

What Is Python Poetry?

Python Poetry is a project management tool that handles dependencies, packaging, and publishing.

Python typically utilizes several tools, such as pip, pipenv, virtualenv, and setuptools, to manage and package projects. Poetry simplifies this process by concentrating all these tasks in a single configuration file: pyproject.toml.

Poetry helps:

• Define and install project dependencies.
• Create and manage isolated virtual environments.
• Build and package Python projects.
• Publish packages to repositories (such as PyPI or others).

Python Poetry employs a modern dependency management approach to ensure consistent and reliable installations across various environments. The workflow is clean, reproducible, and collaborative for CI/CD-based projects.

Why Use Python Poetry?

Python Poetry is an alternative to a traditional Python development tooling stack. It aims to streamline the traditional development process. Developers prefer Python Poetry for the following reasons:

• All-in-one tool. Poetry replaces many Python tools through a single unified flow.
• Simplified dependency management. A single command controls adding, updating, or removing dependencies. It automatically updates necessary files to ensure consistency.
• Automated virtual environments. Poetry creates and manages virtual environments to avoid project conflicts.
• Clean configuration. A single pyproject.toml file manages dependencies, project metadata, and scripts.
• Reproducible installations. A poetry.lock file manages, installs, and ensures the same development environment across different locations.
• Publishing tools. Building and publishing packages to PyPI is simplified through a few commands.

Poetry reduces setup time, avoids common environment issues, and fosters collaboration across teams and systems.

How to Install Python Poetry?

Installing Poetry is a simple and platform-independent process. Use the official installation script provided by the poetry team.

Open a terminal session and run the following cURL command:

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

The script automatically installs the latest stable Poetry version. The installer adds Poetry to the PATH, but you may need to restart the terminal or update your PATH afterward.

To verify the installation, run:

poetry --version

If the installation was successful, the command prints the installed version number.

How to Configure Python Poetry?

Configure Poetry to customize its behavior. The poetry config command allows you to tailor its settings to create a custom environment and add dependency sources.

To see all the current settings, run:

poetry config --list

The output lists all the current configuration settings. To scope settings, use one of the following flags:

• --global. Applies to all projects (default).
• --local. Applies to the current project only.

Below are common configuration examples.

• Store virtual environments in the project directory:

poetry config virtualenvs.in-project true

• Change the storage location for Poetry-managed virtual environments:

poetry config virtualenvs.path [path]

• Add a custom package repository:

poetry config repositories.myrepo [URL]

• Save PyPI authentication credentials for publishing:

poetry config http-basic-pypi [username] [password]

Adjust all other settings as needed to fit your workflow.

How to Use Python Poetry?

Poetry simplifies everyday project tasks from start to finish. It provides a consistent CLI for starting new projects, managing dependencies, and publishing packages. The same interface is used for handling virtual environments, versioning, builds, and more.

Below are several common tasks in Poetry.

How to Create a New Project Using Poetry

To create a new project, use the new command and provide the project name:

poetry new [project-name]

The command creates a standard project structure for a library or package. For single script files, create a new project manually, then run:

poetry init

The init command starts an interactive prompt to define dependencies and metadata.

How to Manage Dependencies Using Poetry

Poetry simplifies dependency management for projects. It maintains the runtime and development dependencies through a single pyproject.toml file.

Provide the version number with additional operators to control the package version. For example, numpy@^1.25 adds any compatible NumPy version starting from 1.25 (such as 1.25.x, but not 2.0).

Add a Dependency

To add a package to a project, run:

poetry add [package]

The command adds the latest compatible package version and updates the pyproject.toml and poetry.lock files.

Add Development Dependencies

For Poetry 1.2 and lower, use the --dev flag to add development tools, such as test frameworks:

poetry add --dev [package]

Newer Poetry versions use dependency groups.

Update Dependencies

To update a package, run:

poetry update [package]

Alternatively, run the command below to update all dependencies:

poetry update

Remove a Dependency

To remove a package from a project and uninstall it, use:

poetry remove [package]

The command also removes any dependent packages.

How to Manage Dependency Groups Using Poetry

Dependency groups help organize packages by their purpose (such as dev tools, testing libraries, or optional packages). Groups help improve clarity and manage large projects effectively.

Grouping is helpful for development vs. production builds and CI/CD pipelines.

Add a Dependency to a Custom Group

To add a dependency to a specific group, use:

poetry add --group [group-name] [package]

The command creates the group if it doesn't exist and adds the package in pyproject.toml (under tool.poetry.group.[group-name].dependencies).

Install Groups

Poetry installs the main dependencies by default. To install a group in a virtual environment, run:

poetry install --with [group-name]

Alternatively, list multiple group names separated by a comma. To install all optional features (listed under tool.poetry.extras), use:

poetry install --all-extras

Group installs are helpful when changing between development, testing, and production environments.

How to Work with Virtual Environments Using Poetry

Poetry manages virtual environments to help isolate dependencies and avoid conflicts. The virtual environment is either local (.venv) or global (controlled by the virtualenvs.in-project parameter).

Create and Activate a Virtual Environment

Install dependencies and set up a virtual environment with:

poetry install

The command creates a .venv directory and installs dependencies. Set the Python interpreter version that Poetry will use for the virtual environment:

poetry env use python3

The command is useful for systems with multiple Python versions. Not running the command automatically picks up the installed version on the system.

Activate the virtual environment with:

poetry env activate

The commands allow running an app or script in an isolated environment. The output shows the source command. Run the provided source command to switch to the environment.

Deactivate the Virtual Environment

To exit the virtual environment, run:

deactivate

If using poetry shell, use the exit command instead.

View Existing Virtual Environments

To view existing environments created by Poetry, run:

poetry env list

The command lists all environments, highlighting the currently active one.

Remove a Virtual Environment

Remove the current local environment with:

rm -rf .venv

The command deletes the in-project virtual environment.

To delete a global environment, use:

poetry env remove [environment-name]

How to Work with Poetry and GitHub Actions

Use Poetry and GitHub actions to automate a project's testing, building, and deployment workflows. Follow these general steps to set up Poetry in a GitHub Actions workflow:

1. Create a workflow file in your repository (e.g., .github/workflows/python.yml).

2. Declare a runner with Python installed.

3. Install dependencies with Poetry.

4. Run tests or execute commands inside the Poetry environment.

See the example configuration below:

name: my-project

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'

    - name: Install Poetry
      run: |
        curl -sSL https://install.python-poetry.org | python3 -
        echo "::add-path::$HOME/.local/bin"

    - name: Install dependencies
      run: poetry install --no-interaction

    - name: Run tests
      run: poetry run pytest

The Poetry installer script sets up Poetry in the workflow and adds to the system PATH to run the command directly. The setup continues by running Poetry commands to install dependencies and runs tests inside a Poetry-managed virtual environment.

How to Publish a Project Using Poetry

To publish a package using Poetry, do the following:

1. Run the following command in the project directory to build the package:

poetry build

The command creates distribution files (a .tar.gz and a .whl file) in the dist/ directory.

2. Poetry publishes to PyPI by default. It requires you to create a PyPI account and generate an API token to publish the project.

Provide __token__ as the username and paste the API token as the password to enable token authentication.

To configure a different repository, add it with:

poetry config repositories.[repository-name] [repository-url]

For example, if using TestPyPI:

poetry config repositories.testpypi https://test.pypi.org/legacy

3. Set your credentials to access the repository:

poetry config http-basic.[repository-name] [username] [password]

For example:

poetry config http-basic.testpypi __token__ [your-token]

The commands do not show an output.

4. Lastly, publish the package. If publishing to the default PyPI repository, use:

poetry publish --username __token__ --password [your-token]

If using a custom repository, use the following format instead:

poetry publish -r [repository-name]

Python Poetry Best Practices

Following best practices when managing Python projects ensures smoother development, collaboration, and deployment. Poetry simplifies dependency management and packaging, but using it efficiently requires picking up some good habits.

The best practices when using Poetry for projects include:

• Use isolated virtual environments. Poetry allows project-specific virtual environments by default. It avoids dependency conflicts between multiple projects. Set virtualenvs.in-project to true and keep .venv/ inside the project folder.
• Use dependency groups. Organize dependencies into groups for better maintainability, such as dev, test, docs, etc.
• Version carefully. Avoid using generalized version specifiers such as *. Be explicit for best reproducibility.
• Commit lock file. Keep the lock file (poetry.lock) in version control to ensure consistent environments.
• Clean and document pyproject.toml. Use comments, group optional dependencies, and avoid unclear extras.
• Use dry run. Before publishing a package, test the publishing with --dry-run. Optionally, use TestPyPI to verify everything works.

Conclusion

This guide explained what Python Poetry is, its purpose, and how to use it to manage Python projects. The tool helps streamline Python projects from start to finish in a professional way.

Next, see how to improve code maintainability through dependency injection.