Installation Guide

Learn how to install and configure Poetry on your system

guide

Poetry is a dependency manager and packaging tool for Python that simplifies project setup, dependency resolution, and packaging. This guide walks you through installing Poetry on Linux/macOS and Windows, adding it to your PATH, configuring environment variables, managing virtual environments, troubleshooting common issues, updating, uninstalling, and getting started quickly.

1. Installation

Linux / macOS (recommended)

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

Alternative (not recommended for production)

pip install --user poetry

Windows (recommended)

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

Alternative (not recommended)

pip install --user poetry

The installer places the poetry binary in ~/.local/bin on Linux/macOS or %APPDATA%\Python\Scripts on Windows. If you use pip, the binary may end up in a user‑site‑packages Scripts directory that is not on PATH by default.

2. Adding Poetry to PATH

Linux / macOS
Add the following line to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export PATH="$HOME/.local/bin:$PATH"

Windows
Add %APPDATA%\Python\Scripts to the system PATH via the Environment Variables UI or run:

setx PATH "%APPDATA%\Python\Scripts;%PATH%"

3. Verifying Installation

Run:

poetry --version

You should see something like Poetry (version 1.8.2).

4. Configuring Environment Variables

Poetry respects several environment variables that influence its behavior. The defaults are shown in parentheses.

Variable	Description	Default
`POETRY_HOME`	Directory where Poetry stores its configuration and cache.	`~/.cache/pypoetry`
`POETRY_VIRTUALENVS_CREATE`	Whether to create virtual environments automatically.	`true`
`POETRY_VIRTUALENVS_IN_PROJECT`	Store virtual env inside the project (`.venv`).	`false`
`POETRY_CACHE_DIR`	Cache directory for downloaded packages.	`~/.cache/pypoetry`
`POETRY_HTTP_BASIC_<REPO>`	Credentials for private PyPI repositories.	–
`POETRY_PYTHON`	Path to the Python interpreter to use.	–

Set these in your shell profile or via Poetry’s own configuration command:

poetry config <key> <value>

Example:

poetry config virtualenvs.in-project true

5. Working with Virtual Environments

Poetry creates a virtual environment per project by default. To store the virtual env inside the project directory, run:

poetry config virtualenvs.in-project true

Activate the environment with:

poetry shell

Deactivate with exit or deactivate.

To run a command without activating, use:

poetry run <command>

6. Common Pitfalls & Troubleshooting

Issue	Symptom	Fix
PATH not updated	`poetry: command not found`	Add the Poetry binary directory to `PATH` as described above.
Multiple Python versions	Poetry uses wrong interpreter	Ensure the desired Python is first in `PATH` or set `POETRY_PYTHON`.
Permission errors on install	`Permission denied`	Use `--user` flag with `pip` or run the installer script with `sudo` only if you want a system‑wide install.
Windows path length limit	Errors when activating virtual env	Enable long path support in Windows or use the in‑project virtualenv option.
Conflicting pip and Poetry	`pip install` installs packages globally, not in Poetry env	Always use `poetry add` or `poetry run pip install` inside the Poetry environment.
Outdated Poetry	Compatibility issues with `pyproject.toml`	Run `poetry self update` to get the latest stable release.
Private repository credentials	Authentication failures	Use `poetry config http-basic.<repo> username password` or set `POETRY_HTTP_BASIC_<REPO>`.

7. Updating Poetry

poetry self update

8. Uninstalling Poetry

If installed via the installer script:

rm -rf ~/.local/bin/poetry
rm -rf ~/.config/pypoetry
rm -rf ~/.cache/pypoetry

If installed via pip:

pip uninstall poetry

9. Quick Start

Create a new project:

poetry new myproject
cd myproject

Add dependencies:

poetry add requests

Run a script:

poetry run python script.py