• initialize a pre-existing project: poetry init

  • add package: poetry add <package>

  • install current project with dependencies: poetry install

  • publish (and build) to PyPI: poetry publish --build -u <username> -p <password>

  • update Poetry itself: poetry self update

Dependency Groups & Extras#

  • To declare a set of dependencies, which add additional functionality to the project during runtime, use extras instead.

  • add dependency: poetry add <package>

  • add dependency in a group (lint, test, etc.): poetry add --group <group> <package>

  • add optional dependency: poetry add --optional <package>

There currently is no support for making optional packages part of a specific group during their addition. You have to maintain this section in the pyproject.toml file by hand:

<group_name> = ["package"]


  • see locale config: poetry config --list

  • store env. in locale project in .venv: poetry config virtualenvs.in-project true --local

    • see https://python-poetry.org/docs/configuration/#virtualenvsin-project

    • this creates a poetry.toml file in the locale project when it is not available

  • always copy python into venv: poetry config virtualenvs.options.always-copy true

  • poetry config virtualenvs.prefer-active-python true

  • config file on Mac: ~/Library/Application\ Support/pypoetry/config.toml

  • Poetry directories on Mac:

    • ~/Library/Caches/pypoetry

    • venvs: ~/Library/Caches/pypoetry/virtualenvs

    • ~/Library/Application\ Support/pypoetry

    • ~/.local/bin with a symlink to the poetry executable

Lint Example#

black = "*"
ruff = "*"
mypy = "*"
mdformat-gfm = "*"
mdformat-frontmatter = "*"
mdformat-footnote = "*"

line-length = 119
target-versions = ["py38", "py39", "py310", "py311"]

select = [
  "E",  # pycodestyle
  "F",  # pyflakes
  "I",  # isort
line-length = 119
fixable = ["I"]
target-version = "py38"

ignore_missing_imports = true


  • Where is the Poetry cache dir at Mac? ~/Library/Application Support/pypoetry