liminfoPoetryref
Free reference guide: Poetryref
About Poetryref
The Poetry Command Reference is a structured quick-reference covering all essential Poetry commands for Python project management. Poetry is a modern dependency management and packaging tool that uses pyproject.toml as its single source of truth, replacing the fragmented workflow of pip, virtualenv, and setup.py. This reference covers six major categories: project initialization, dependency management (add, remove, update, lock), build and publish workflows, configuration, and virtual environment management.
Python developers, data scientists, and DevOps engineers use this reference when working with Poetry in daily development, CI/CD pipelines, and library publishing workflows. Whether you are creating a new project with `poetry new`, pinning dependencies with `poetry lock`, publishing a package to PyPI with `poetry publish`, or switching Python versions with `poetry env use`, this reference provides the exact syntax and real-world examples you need.
The reference is organized into six categories — Project, Dependencies, Build, Publish, Config, and Virtual Env — to match the natural workflow of Python development. Each entry includes the full command syntax, a concise description, and a runnable example that shows the command in realistic context. The data covers Poetry 1.x and 2.x conventions including dependency groups (`--group dev`), lock file management, and the `poetry.toml` local config format.
Key Features
- Full coverage of Poetry project commands: new, init, check, list, self update
- Dependency lifecycle commands: add, remove, install, update, lock, show with --tree and --outdated flags
- Dependency group support: --group dev for pytest, black, mypy and other dev tools
- Build and publish workflow: poetry build (sdist + wheel), poetry version (semver bump), poetry publish
- Private repository configuration: repositories, pypi-token, and publish --repository
- Virtual environment management: env use, env info, env list, env remove, poetry shell
- Configuration commands: poetry config --list, virtualenvs.in-project, local poetry.toml
- Real runnable examples for every command showing actual project structure and output
Frequently Asked Questions
What is Poetry and why should I use it over pip?
Poetry is a Python dependency management and packaging tool that solves several pip limitations. It uses pyproject.toml to declare both runtime and dev dependencies, automatically creates and manages isolated virtual environments, generates a poetry.lock file for reproducible installs, and provides a simple workflow for building and publishing packages to PyPI — all with a single tool.
What is the difference between poetry install and poetry update?
`poetry install` installs exactly the versions recorded in poetry.lock, ensuring reproducible builds. `poetry update` resolves the latest versions that satisfy your pyproject.toml constraints and updates poetry.lock. Use install in CI/CD and production; use update to intentionally upgrade dependencies.
How do I add a development-only dependency in Poetry?
Use `poetry add --group dev package-name`. For example: `poetry add --group dev pytest black mypy`. This adds the package to the [tool.poetry.group.dev.dependencies] section of pyproject.toml and excludes it when installing with `poetry install --without dev`.
What does poetry lock --no-update do?
`poetry lock --no-update` regenerates the poetry.lock file without upgrading any package versions. This is useful when you have modified pyproject.toml (e.g., added a new dependency) but want to preserve the existing resolved versions for all other packages.
How do I use a specific Python version with Poetry?
Run `poetry env use python3.11` or `poetry env use /usr/local/bin/python3.12` to create a virtual environment with a specific Python interpreter. You can list all linked environments with `poetry env list` and switch between them by running `poetry env use` again.
How do I publish a package to PyPI with Poetry?
First build the package with `poetry build` (creates dist/*.whl and dist/*.tar.gz), then run `poetry publish`. You need to authenticate with your PyPI API token: `poetry config pypi-token.pypi YOUR_TOKEN`. Use `poetry publish --build` to build and publish in one step.
What is the difference between virtualenvs.in-project true and the default behavior?
By default, Poetry creates virtual environments in a central cache directory (e.g., ~/.cache/pypoetry/virtualenvs/). With `poetry config virtualenvs.in-project true`, Poetry creates the .venv directory inside your project root, making it visible to editors like VS Code that look for .venv in the workspace.
How do I run tests or scripts inside the Poetry virtual environment?
Use `poetry run command` to execute any command inside the virtual environment without activating it. For example: `poetry run pytest`, `poetry run python main.py`, `poetry run black .`. Alternatively, `poetry shell` opens an interactive shell session with the virtual environment activated.