• 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>

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
  • 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
    • ~/Library/Application\ Support/pypoetry
    • ~/.local/bin with a symlink to the poetry executable

Lint Example

black = "*"
ruff = "*"
mypy = "*"
mdformat = "*"

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
Last modified August 6, 2023: Update poetry.md (89a0d22)