Poetry Python

Poetry cheatsheet — manage Python dependencies and packages. poetry add requests, poetry install, poetry run, poetry publish, poetry shell. Modern Python packaging.

6 min read

What it is

Poetry is a tool for dependency management and packaging in Python, simplifying project setup, dependency resolution, and building/publishing packages.

Installation

Linux / macOS

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

Windows (PowerShell)

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

Verifying Installation

poetry --version

Core Concepts

  • pyproject.toml: The central configuration file for your Poetry project. It defines project metadata, dependencies, build system requirements, and more.
  • Virtual Environments: Poetry automatically manages isolated virtual environments for each project, ensuring dependency consistency and avoiding conflicts.
  • Dependency Resolution: Poetry uses a sophisticated algorithm to find a compatible set of dependencies for your project, avoiding version conflicts.
  • Lock File (poetry.lock): This file records the exact versions of all installed dependencies, ensuring reproducible builds.

Commands / Usage

Project Initialization & Setup

  • Create a new project:

    poetry new my-new-project

    Creates a new project structure with a pyproject.toml file.

  • Initialize an existing project:

    cd existing-project
poetry init

    Walks you through creating a pyproject.toml for an existing directory.

  • Add a dependency:

    poetry add requests

    Adds the requests library to your project and updates pyproject.toml.

  • Add a development dependency:

    poetry add pytest --group dev

    Adds pytest as a development dependency, used only during development or testing.

  • Add a dependency with a specific version:

    poetry add django@^3.2

    Adds django with a caret-compatible version constraint (e.g., 3.2.x but not 4.0.x).

  • Add a dependency with a wildcard version:

    poetry add flask@~2.0.0

    Adds flask with a tilde-compatible version constraint (e.g., 2.0.x but not 2.1.x).

  • Add a dependency from a Git repository:

    poetry add git+https://github.com/python-poetry/poetry.git#master

    Adds a dependency directly from a Git repository.

  • Remove a dependency:

    poetry remove requests

    Removes the requests library and updates pyproject.toml.

  • Install dependencies from poetry.lock:

    poetry install

    Installs all dependencies defined in poetry.lock into the virtual environment. This is crucial for reproducible builds.

  • Install dependencies from pyproject.toml (resolving versions):

    poetry install --no-dev

    Installs dependencies defined in pyproject.toml but skips development dependencies.

  • Update dependencies:

    poetry update

    Updates all dependencies to their latest allowed versions according to pyproject.toml and updates poetry.lock.

  • Update a specific dependency:

    poetry update requests

    Updates only the requests dependency.

  • Show current project dependencies:

    poetry show

    Lists all installed dependencies in the current environment.

  • Show all dependencies (including transitive):

    poetry show --tree

    Displays dependencies in a tree format, showing which package requires which.

  • Show outdated dependencies:

    poetry show --outdated

    Lists dependencies that have newer versions available.

Running Scripts & Executables

  • Run a command within the virtual environment:

    poetry run python my_script.py

    Executes my_script.py using the Python interpreter from the project’s virtual environment.

  • Run a script defined in pyproject.toml:

    poetry run start

    Executes a command mapped to a script name in the [tool.poetry.scripts] section of pyproject.toml.

  • Execute a command directly (if it’s a Poetry-managed executable):

    poetry run flask run

    Runs the flask command from within the virtual environment.

Building & Publishing

  • Build the package (sdist and wheel):

    poetry build

    Creates distribution archives (source distribution and wheel) in the dist/ directory.

  • Publish the package to PyPI:

    poetry publish

    Uploads the built package to the Python Package Index (requires configuration of API token).

  • Publish to a custom repository:

    poetry publish --repository testpypi

    Publishes to a specified repository (e.g., TestPyPI).

Virtual Environment Management

  • Show the path to the virtual environment:

    poetry env info

    Displays information about the current virtual environment, including its path.

  • List all virtual environments managed by Poetry:

    poetry env list

    Shows all virtual environments Poetry has created for your projects.

  • Remove a virtual environment:

    poetry env remove python3.9

    Removes the virtual environment associated with a specific Python version.

  • Execute a command in a specific environment:

    poetry run --python 3.9 python my_script.py

    Runs a command using a specific Python interpreter managed by Poetry.

  • Clear the dependency cache:

    poetry cache clear --all pypi

    Clears the cache for a specific repository (e.g., PyPI).

Configuration

  • Set a configuration value:

    poetry config virtualenvs.in-project true

    Configures Poetry to create virtual environments inside the project directory (default is in a central cache).

  • Get a configuration value:

    poetry config virtualenvs.in-project

    Retrieves the value of a specific configuration setting.

  • List all configuration values:

    poetry config --list

    Shows all current Poetry configuration settings.

  • Add a repository:

    poetry source add my-repo https://my.custom.repo/simple/

    Adds a custom package repository.

  • Remove a repository:

    poetry source remove my-repo

    Removes a previously added custom repository.

Common Patterns

  • Creating a new project and installing dependencies:

    poetry new my-awesome-package
cd my-awesome-package
poetry add requests pandas numpy
poetry install

    Sets up a new project, adds common data science libraries, and ensures they are installed.

  • Running tests in a CI/CD pipeline:

    poetry install --no-dev --no-root # Install only dependencies, skip project package
poetry run pytest

    Ensures only production dependencies are installed and then runs tests.

  • Setting up a project with a specific Python version:

    poetry env use python3.10
poetry install

    Explicitly sets the Python interpreter for the project’s virtual environment.

  • Adding a package from a private Git repository with authentication:

    poetry add git+ssh://git@github.com/my-org/my-private-repo.git@main#egg=my-private-repo

    Uses SSH to clone a private repository. Ensure your SSH keys are set up.

  • Creating a package and publishing to TestPyPI:

    poetry build
poetry publish --repository testpypi

    Builds your package and uploads it to TestPyPI for testing before a full release.

  • Getting a shell within the virtual environment:

    poetry shell

    Activates the project’s virtual environment, allowing you to run commands directly without poetry run. Type exit to leave the shell.

Gotchas

  • poetry install vs. poetry update: poetry install installs dependencies exactly as specified in poetry.lock. poetry update resolves new versions based on pyproject.toml and updates poetry.lock. Always use poetry install in CI/CD to ensure reproducibility.
  • poetry run vs. poetry shell: poetry run is generally preferred in scripts and CI/CD as it’s explicit. poetry shell activates the environment, which can be convenient for interactive work but might lead to unexpected behavior if not managed carefully.
  • Virtual environment location: By default, Poetry stores virtual environments in a central cache. Use poetry config virtualenvs.in-project true to keep them within your project directory for easier management, especially when working on multiple projects.
  • Lock file management: Never commit poetry.lock to version control if you are not the primary maintainer of the project and dependencies are expected to be flexible. However, for most applications and libraries, committing poetry.lock is crucial for reproducible builds.
  • Dependency conflicts with older packages: Poetry’s dependency resolver is powerful but can sometimes struggle with very complex dependency graphs or older packages that have strict, conflicting requirements. Explicitly pinning versions in pyproject.toml or poetry.lock can help.
  • --no-dev flag: When using poetry install --no-dev, only production dependencies are installed. This is useful for deployment but means development tools like linters or test runners won’t be available.
  • poetry.lock and Git: If you’re working on a shared project, ensure poetry.lock is committed to your repository so all team members use the exact same dependency versions.