Poetry Cheatsheet

Poetry Cheatsheet

Installation

Platform	Command
Linux/macOS (Official)	`curl -sSL https://install.python-poetry.org \
macOS (Homebrew)	brew install poetry
Windows (PowerShell)	`(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content \
Any Platform (pipx)	pipx install poetry
Verify Installation	poetry --version
Update Poetry	poetry self update
Update to Specific Version	poetry self update 1.5.0
Add to PATH (if using official installer):

export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc for persistence

Basic Commands

Command	Description
poetry new my-project	Create new project with standard structure
poetry new my-project --src	Create project with src layout
poetry init	Initialize Poetry in existing project (interactive)
poetry install	Install all dependencies from lock file
poetry add requests	Add package to dependencies
poetry add pytest --group dev	Add package to dev dependencies
poetry remove requests	Remove package from dependencies
poetry update	Update all dependencies to latest allowed versions
poetry update requests	Update specific package
poetry show	List all installed packages
poetry show --tree	Show dependency tree
poetry show requests	Show details of specific package
poetry lock	Generate/update poetry.lock file
poetry check	Validate pyproject.toml and poetry.lock
poetry run python script.py	Run command in virtual environment
poetry run pytest	Run tests in virtual environment
poetry shell	Activate virtual environment
poetry env info	Show virtual environment information
poetry env list	List all virtual environments
poetry build	Build source and wheel distributions

Advanced Usage

Command	Description
poetry add requests@^2.28.0	Add package with caret version constraint (>=2.28.0 <3.0.0)
poetry add requests@~2.28.0	Add package with tilde constraint (>=2.28.0 <2.29.0)
poetry add "requests>=2.28,<3.0"	Add package with complex version range
poetry add git+https://github.com/user/repo.git	Add package from Git repository
poetry add ./path/to/package --editable	Add local package in editable mode
poetry install --without dev,test	Install dependencies excluding specific groups
poetry install --with docs	Install dependencies including optional group
poetry install --only main	Install only main dependencies
poetry install --sync	Sync environment with lock file (remove extras)
poetry update --dry-run	Preview dependency updates without applying
poetry show --outdated	Show packages with available updates
poetry show --latest	Show latest available versions
poetry env use python3.11	Use specific Python version for environment
poetry env use /usr/bin/python3.9	Use specific Python interpreter path
poetry env remove python3.11	Remove specific virtual environment
poetry export -f requirements.txt -o requirements.txt	Export dependencies to requirements.txt
poetry export --without-hashes -o requirements.txt	Export without hash verification
poetry publish	Publish package to PyPI
poetry publish --build	Build and publish in one command
poetry publish --dry-run	Test publish without uploading
poetry config --list	List all configuration settings
poetry config virtualenvs.in-project true	Create .venv in project directory
poetry source add private https://pypi.example.com/simple/	Add custom package source
poetry cache clear pypi --all	Clear Poetry cache

Configuration

Primary Configuration File: pyproject.toml

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "Project description"
authors = ["Your Name <you@example.com>"]
readme = "README.md"
license = "MIT"
homepage = "https://example.com"
repository = "https://github.com/user/repo"
keywords = ["keyword1", "keyword2"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Programming Language :: Python :: 3.11",
]
packages = [{include = "my_package"}]

[tool.poetry.dependencies]
python = "^3.11"
requests = "^2.28.0"
pydantic = {version = "^2.0", optional = true}

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
black = "^23.0"
mypy = "^1.0"

[tool.poetry.group.docs.dependencies]
sphinx = "^5.0"

[tool.poetry.extras]
data = ["pydantic"]

[tool.poetry.scripts]
my-cli = "my_package.cli:main"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Global Configuration Settings

Setting	Command	Description
Create venv in project	poetry config virtualenvs.in-project true	Create .venv folder in project root
Set venv path	poetry config virtualenvs.path "/path/to/venvs"	Custom location for virtual environments
Parallel installation	poetry config installer.parallel true	Enable parallel package installation
Max workers	poetry config installer.max-workers 10	Set maximum parallel workers
Cache directory	poetry config cache-dir "/path/to/cache"	Set custom cache location
PyPI token	poetry config pypi-token.pypi your-token	Set PyPI authentication token
View setting	poetry config virtualenvs.in-project	Display specific configuration value
Unset setting	poetry config virtualenvs.in-project --unset	Remove configuration setting
Local config	poetry config --local virtualenvs.in-project true	Set project-specific configuration

Version Constraint Operators

Operator	Example	Meaning
Caret ^	^2.28.0	>=2.28.0 <3.0.0 (compatible versions)
Tilde ~	~2.28.0	>=2.28.0 <2.29.0 (patch updates)
Exact	2.28.0	Exactly version 2.28.0
Greater/Equal	>=2.28.0	Version 2.28.0 or higher
Range	>=2.28,<3.0	Between 2.28 and 3.0
Wildcard	2.28.*	Any patch version of 2.28
Latest	@latest	Latest available version

Common Use Cases

Use Case 1: Starting a New Python Project

# Create new project with src layout
poetry new my-app --src

# Navigate to project
cd my-app

# Add production dependencies
poetry add fastapi uvicorn pydantic-settings

# Add development dependencies
poetry add pytest pytest-cov black mypy --group dev

# Install all dependencies
poetry install

# Activate virtual environment
poetry shell

Use Case 2: Converting Existing Project to Poetry

# Navigate to existing project
cd existing-project

# Initialize Poetry (interactive)
poetry init

# Add existing dependencies
poetry add requests flask sqlalchemy

# Add dev dependencies from requirements-dev.txt
poetry add pytest black flake8 --group dev

# Generate lock file
poetry lock

# Install everything
poetry install

Use Case 3: Managing Multiple Dependency Groups

# Install with documentation dependencies
poetry install --with docs

# Install without test dependencies
poetry install --without test

# Install only main dependencies (no dev/test)
poetry install --only main

# Add dependencies to specific groups
poetry add sphinx sphinx-rtd-theme --group docs
poetry add locust --group perf

Use Case 4: Building and Publishing a Package

# Update version in pyproject.toml
poetry version patch  # 0.1.0 -> 0.1.1
poetry version minor  # 0.1.1 -> 0.2.0
poetry version major  # 0.2.0 -> 1.0.0

# Build package
poetry build

# Test publish to TestPyPI
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish -r testpypi --username __token__ --password $TEST_PYPI_TOKEN

# Publish to PyPI
poetry publish --username __token__ --password $PYPI_TOKEN

Use Case 5: Working with Private Package Repositories

# Add private repository
poetry source add --priority=supplemental private-repo https://pypi.company.com/simple/

# Configure authentication
poetry config http-basic.private-repo username password

# Or use token authentication
poetry config pypi-token.private-repo your-token

# Add package from private repo
poetry add internal-package

# Publish to private repo
poetry publish -r private-repo

Use Case 6: CI/CD Integration

# Install Poetry in CI
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies (no dev dependencies)
poetry install --without dev --no-interaction --no-ansi

# Export for Docker or other tools
poetry export -f requirements.txt --output requirements.txt --without-hashes

# Run tests
poetry run pytest

# Build package
poetry build

Best Practices

• Commit poetry.lock: Always commit the lock file to version control to ensure reproducible builds across all environments and team members.

• Use dependency groups: Organize dependencies into logical groups (dev, test, docs) instead of the deprecated --dev flag for better control and flexibility.

• Pin Python version: Specify the Python version constraint in pyproject.toml to prevent compatibility issues across different environments.

• Use poetry.lock for applications: For applications and services, rely on the lock file for exact versions. For libraries, test against the range of versions specified in pyproject.toml.

• Prefer poetry install --sync: In CI/CD pipelines, use --sync to ensure the environment exactly matches the lock file, removing any extraneous packages.

• Set virtualenvs.in-project: Configure Poetry to create virtual environments in the project directory (poetry config virtualenvs.in-project true) for easier IDE integration and cleanup.

• Use version constraints wisely: Use caret (^) for most dependencies to allow compatible updates, but use exact versions for packages with unstable APIs or breaking changes.

• Export for compatibility: Generate requirements.txt files when needed for tools that don’t support Poetry, especially in Docker containers or legacy systems.

• Keep Poetry updated: Regularly update Poetry itself (poetry self update) to benefit from bug fixes, performance improvements, and new features.

• Use poetry check before commits: Validate your pyproject.toml and poetry.lock files before committing to catch configuration errors early.

Troubleshooting

Issue	Solution
poetry: command not found	Add Poetry to PATH: export PATH="$HOME/.local/bin:$PATH" or restart terminal after installation
Virtual environment not activating	Use poetry shell or run commands with poetry run. Check poetry env info to verify environment exists
Dependency resolution takes too long	Clear cache with poetry cache clear pypi --all, update Poetry, or try poetry lock --no-update
Lock file out of sync errors	Run poetry lock --no-update to regenerate lock file, or poetry install --sync to match environment to lock
Package not found in private repo	Verify source configuration with poetry source show, check authentication with poetry config --list
SolverProblemError during install	Check for conflicting version constraints in pyproject.toml, try updating dependencies with poetry update
Poetry using wrong Python version	Specify Python explicitly: poetry env use python3.11 or poetry env use /path/to/python
Cannot publish to PyPI (authentication)	Configure token: poetry config pypi-token.pypi your-token or use --username and --password flags
poetry.lock merge conflicts	Run poetry lock --no-update after resolving conflicts in pyproject.toml to regenerate lock file
Slow package installation	Enable parallel installation: poetry config installer.parallel true and adjust workers if needed
IDE not detecting virtual environment	Use poetry config virtualenvs.in-project true and point IDE to .venv directory in project root