Poetry Command Not Found: Complete Installation and Fix Guide

When you encounter the poetry: command not found error, it's typically because Poetry isn't properly added to your system's PATH environment variable. This comprehensive guide covers solutions for Windows, macOS, and Linux/WSL environments.

Understanding the Problem

Poetry is a Python dependency management tool that needs to be accessible from your command line. The error occurs when:

• Poetry is installed but not in your system PATH
• Shell configuration files aren't properly configured
• Installation was incomplete or corrupted
• System restarts cleared temporary PATH additions

Recommended Installation Methods

Official Installation (All Platforms)

The Poetry team recommends using their official installer:

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

After installation, the output will show the exact path where Poetry was installed and instructions for adding it to your PATH.

Using pipx (Recommended)

pipx isolates Python applications and automatically handles PATH configuration:

# Install pipx first if needed
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install Poetry with pipx
pipx install poetry

Platform-Specific Installers

macOS - Homebrew

brew install poetry

Windows - Chocolatey

choco install poetry

Ubuntu/Debian - Official

sudo apt update
sudo apt install python3-poetry

PATH Configuration Solutions

For macOS and Linux/WSL Users

Most Unix-like systems install Poetry to ~/.local/bin. Add this to your shell configuration:

1. Find your shell type:

   echo $SHELL

2. Edit the appropriate configuration file:

   zsh - .zshrc

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

   bash - .bashrc

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

   bash - WSL

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

WARNING

If your shell configuration file doesn't exist, create it first:

touch ~/.zshrc  # or ~/.bashrc

For Windows Users

Windows typically installs Poetry to one of these locations:

• %USERPROFILE%\AppData\Roaming\pypoetry\venv\Scripts
• %APPDATA%\Python\Scripts
• %USERPROFILE%\.local\bin

Using PowerShell:

# Add to PATH temporarily
$env:Path += ";$env:USERPROFILE\AppData\Roaming\pypoetry\venv\Scripts"

# Add to PATH permanently
[Environment]::SetEnvironmentVariable("Path", 
    "$env:Path;$env:USERPROFILE\AppData\Roaming\pypoetry\venv\Scripts", 
    [EnvironmentVariableTarget]::User)

Using System Properties:

1. Press Win + R, type sysdm.cpl, and press Enter
2. Click "Environment Variables"
3. Under "User variables", select "Path" and click "Edit"
4. Click "New" and add the Poetry installation path
5. Click OK to save changes

Verification and Testing

After configuration, verify Poetry is accessible:

poetry --version

You should see output similar to:

Poetry (version 1.8.2)

Troubleshooting Common Issues

Installation Appears Successful but Command Not Found

This indicates a PATH configuration issue. Check where Poetry was installed:

# Unix systems
find ~ -name "poetry" -type f -executable 2>/dev/null

# Windows PowerShell
Get-ChildItem -Path $env:USERPROFILE -Recurse -Filter "poetry*" -File | Where-Object {$_.Name -eq "poetry.exe"}

Add the discovered path to your system PATH using the methods above.

Shell Plugin Requirement (Poetry 2.0+)

For Poetry versions 2.0 and later, you may need the shell plugin:

poetry self add poetry-plugin-shell

Reinstalling Poetry

If configuration seems correct but Poetry still isn't working, try reinstalling:

# Uninstall first
pip uninstall poetry

# Reinstall using recommended method
curl -sSL https://install.python-poetry.org | python3 -

Platform-Specific Notes

Windows with WSL

When using Poetry in WSL (Windows Subsystem for Linux):

1. Install Poetry within your WSL distribution, not Windows
2. Use the Linux installation methods above
3. Ensure you're editing WSL configuration files, not Windows ones

macOS Specifics

Recent macOS versions use zsh as the default shell. Ensure you're modifying ~/.zshrc rather than ~/.bash_profile or ~/.bashrc.

Best Practices

1. Use pipx for isolation: pipx keeps Poetry and its dependencies separate from your system Python
2. Verify installation: Always run poetry --version after installation
3. Keep updated: Regularly update Poetry with poetry self update
4. Check documentation: Refer to official Poetry documentation for latest instructions

INFO

The deprecated get-poetry.py installer mentioned in some older solutions should no longer be used. Always use the current official installation method.

By following these guidelines, you should be able to resolve the "poetry: command not found" error and maintain a stable Poetry installation across system restarts.