A quick, no-fluff guide to using Poetry — Python’s all-in-one tool for dependency management, virtual environments, and publishing packages. Includes the most common commands for setup, dependency handling, versioning, and project maintenance — perfect for beginners or anyone switching from pip/venv to Poetry.

poetery-101.md

Poetry 101

It a all in one tool that:-

• Manages virtual env for python projects
• Manages dependencies for python projects
• Publish python packages to PyPI

Installation

pip install poetry

Initialize a new project

This will create a pyproject.toml file

poetry init

Create a virtual env

poetry install

See info about your virtual env

poetry env info

Update virual env location as part of the project folder

Delete existing virtual env folder and then run the following command followed by the install command, make sure to add the .venv/ folder in .gitignore

poetry config virtualenvs.in-project true

Activate the virtual env

Run the follwing command then you can run any project related command after that

poetry shell
poetry run COMMAND

Get out of the virtual env shell

Run this while in the activated shell

exit

Deactivate the virual env shell

Run this while in the activated shell

deactivate

List all active envs

poetry env list

Adding dependencies

This will add the PACKAGE_NAME to the pyproject.toml

poetry add PACKAGE_NAME

Remove dependencies

This will remove the PACKAGE_NAME from the pyproject.toml

poetry remove PACKAGE_NAME

See list of dependencies installed

poetry show

poetry.lock

This file is automatically created when you run poetry install or poetry add PACKAGE_NAME. It locks the dependencies to specific versions to ensure consistency across different environments.

Semantic versioning in dependencies

poetry add [email protected] #Install the latest minor and patch version that matches 4.17.1
poetry add PACKAGE_NAME@^4.17.1 # Install the latest minor and patch version that matches 4.x.x (but not 5.0.0)
poetry add PACKAGE_NAME~4.14.1 # Install the latest patch version that matches 4.17.x (but not 4.18.0).
poetry add "PACKAGE_NAME@*" # Installs the latest minor and patch version, but will also update to the last major version if available when updated

Update dependency versions

poetry update

Package versioning

Command	New version (example)	Effect / Meaning
poetry version	-	prints current version (just shows current)
poetry version patch	1.2.4 (from 1.2.3)	bump patch version — bug fixes only
poetry version minor	1.3.0 (from 1.2.3)	bump minor version — backward-compatible feature additions
poetry version major	2.0.0 (from 1.2.3)	bump major version — breaking changes
poetry version prepatch	1.2.4-alpha.0	create a pre-release
poetry version 3.0.0	3.0.0	explicitly set version