Python Poetry

# Official installer — keeps Poetry isolated from your Python envs
curl -sSL https://install.python-poetry.org | python3 -

# Verify the install
poetry --version

# Enable tab completion (bash example)
poetry completions bash >> ~/.bash_completion

# Store virtualenvs inside the project directory (.venv/) instead of the global cache
# Useful for IDE auto-discovery and Docker layer caching
poetry config virtualenvs.in-project true

# See all current config values
poetry config --list

# Set the PyPI token for publishing (stored securely in keyring)
poetry config pypi-token.pypi <your-token>

# Scaffold a new project with a standard layout
poetry new my-project

# Scaffold with src/ layout (recommended for packages)
poetry new --src my-project

# Initialise Poetry in an existing directory interactively
cd existing-project
poetry init

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "A short description"
authors = ["Your Name <[email protected]>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"          # minimum Python version constraint
requests = "^2.31"        # caret: compatible with 2.31.*
pydantic = { version = "^2.0", extras = ["email"] }  # with extras

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
ruff = "^0.4"

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

# Add a runtime dependency (updates pyproject.toml + poetry.lock)
poetry add requests

# Add with a version constraint
poetry add 'django>=4.2,<5'

# Add a dev-only dependency (won't be installed in production)
poetry add --group dev pytest ruff

# Add a package with extras (e.g. async support)
poetry add 'uvicorn[standard]'

# Remove a dependency
poetry remove requests

# Install all dependencies from poetry.lock (reproducible)
poetry install

# Install without dev dependencies (CI / production)
poetry install --without dev

# Update all dependencies to their latest allowed versions
poetry update

# Update a single package
poetry update requests

# Show what would change without applying it
poetry update --dry-run

# List all installed packages with versions
poetry show

# Show the full dependency tree
poetry show --tree

# Show outdated packages
poetry show --outdated

# Check pyproject.toml for validity issues
poetry check

# Run a command inside the project's virtualenv without activating it
poetry run python script.py
poetry run pytest

# Spawn a shell with the virtualenv activated
poetry shell

# List virtualenvs associated with the project
poetry env list

# Switch to a specific Python version (must already be installed)
poetry env use python3.12

# Delete the current virtualenv (useful to rebuild from scratch)
poetry env remove python3.12

# In pyproject.toml — define CLI entrypoints and shortcut scripts
[tool.poetry.scripts]
# Installs a `my-cli` command pointing to the start() function
my-cli = "my_project.cli:start"

[tool.poetry.scripts.dev]
# Custom shortcut: `poetry run dev` triggers this shell command
# (requires poethepoet plugin for task runner support)
server = "uvicorn my_project.main:app --reload"

# Build both a source distribution (.tar.gz) and a wheel (.whl)
poetry build

# Build only a wheel (faster, preferred for most packages)
poetry build --format wheel

# Artifacts land in dist/
ls dist/

# Bump the version (patch = 0.1.0 → 0.1.1, minor → 0.2.0, major → 1.0.0)
poetry version patch

# Build fresh artifacts
poetry build

# Publish to PyPI (uses token set via `poetry config pypi-token.pypi`)
poetry publish

# Build + publish in one step
poetry publish --build

# Publish to a private/custom repository
poetry publish --repository my-private-repo