Master Python Dependency Management with Poetry: Installation & Usage Guide

Previously we introduced pipenv; now we discuss Poetry, a Python virtual‑environment and dependency‑management tool that also supports packaging and publishing.

1. Installing Poetry

On macOS, the recommended installation method from the official site installs Poetry to $HOME/.poetry/bin:

curl -sSL https://install.python-poetry.org | python -

If network issues cause timeouts, refer to the linked article for proxy configuration. Alternatively, Poetry can be installed via pipx:

# Install pipx on macOS
brew install pipx
pipx ensurepath

# Install Poetry with pipx
pipx install poetry
poetry --version

# Upgrade Poetry
pipx upgrade poetry

# Uninstall Poetry
pipx uninstall poetry

# Enable shell completions
mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry
# Add to .zshrc and source
source ~/.zshrc

2. Using Poetry

Creating a project

poetry new demo1

demo1
├── pyproject.toml
├── README.rst
├── demo1
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_demo1.py

Creating a virtual environment

cd demo1
poetry install

Setting a PyPI source

Add the following to the end of pyproject.toml to use the Aliyun mirror:

[[tool.poetry.source]]
name = "aliyun"
url = "http://mirrors.aliyun.com/pypi/simple"
default = true

Activating and using the virtual environment

# Run a script without activating the environment
poetry run python start.py

# Activate the environment
poetry shell

# Install a package
poetry add flask

# List installed packages
poetry show

# Show details of a specific package
poetry show flask

# Remove a package
poetry remove flask

# Exit the environment
exit

# Show the environment path
poetry env info --path

# Remove the environment
poetry env remove /full/path/to/python

3. Using Poetry in PyCharm

Poetry is available in PyCharm as a plugin. Install the plugin, then create a new project and select Poetry as the interpreter.