{"id":677,"library":"poetry","title":"Poetry: Python Dependency Management","description":"Poetry is a comprehensive tool for Python dependency management and packaging, leveraging `pyproject.toml` for configuration and a `poetry.lock` file for consistent, reproducible environments. It handles dependency resolution, virtual environment management, and project building. The current version is 2.3.2, with frequent minor and patch releases, though without a fixed release cycle.","status":"active","version":"2.3.2","language":"python","source_language":"en","source_url":"https://github.com/python-poetry/poetry","tags":["packaging","dependency management","build tool","cli","virtual environments"],"install":[{"cmd":"pipx install poetry","lang":"bash","label":"Recommended via pipx (isolated environment)"},{"cmd":"curl -sSL https://install.python-poetry.org | python3 -","lang":"bash","label":"Official installer (Linux/macOS)"},{"cmd":"(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -","lang":"powershell","label":"Official installer (Windows PowerShell)"}],"dependencies":[{"reason":"Poetry itself requires Python >=3.10 and <4.0. Note that Poetry manages your project's Python versions but does not install Python interpreters for you.","package":"python","optional":false},{"reason":"Lightweight PEP 517 build backend implementation for Poetry, typically used transparently by Poetry or other build frontends like pip.","package":"poetry-core","optional":false}],"imports":[],"quickstart":{"code":"# 1. Create a new project\npoetry new my-project\n\n# 2. Navigate into the project directory\ncd my-project\n\n# 3. Add a dependency\npoetry add requests\n\n# 4. Install project dependencies (creates virtual environment if needed)\npoetry install\n\n# 5. Run a command within the project's virtual environment\npoetry run python -c \"import requests; print('Requests is installed!')\"","lang":"bash","description":"Initialize a new Poetry project, add dependencies, install them into a managed virtual environment, and execute commands within that environment."},"warnings":[{"fix":"Install necessary plugins (`poetry self add poetry-plugin-export`, `poetry self add poetry-plugin-shell`), use `poetry env activate` instead of `poetry shell`, and review `poetry add` usage for optional dependencies. Ensure Python 3.10+ is used for projects requiring it.","message":"Poetry 2.0 introduced significant breaking changes. Commands like `poetry export` and `poetry shell` are no longer core features and require separate plugins (`poetry-plugin-export` and `poetry-plugin-shell`). `poetry env activate` is the recommended replacement for `poetry shell`. The interface for `poetry add --optional` also changed. The minimum Python version for generated SDKs changed to 3.10.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade project's Python version to 3.10 or higher, or explicitly use a Poetry version that supports Python 3.9 (e.g., `poetry==2.2.*`).","message":"Python 3.9 support was dropped in Poetry 2.3.0. Projects requiring 3.9 will need to use an older Poetry version or upgrade their Python environment.","severity":"breaking","affected_versions":">=2.3.0"},{"fix":"When using PEP 735 dependency groups, ensure you are running Poetry 2.3.0 or later. If using older 2.2.x, manually run `poetry lock` to ensure `poetry.lock` is up-to-date after modifying dependency groups.","message":"PEP 735 dependency groups (introduced in Poetry 2.2.0) had issues with lock file hashing, meaning changes to these groups were not always reflected in `poetry.lock`. This was fixed in Poetry 2.3.0.","severity":"gotcha","affected_versions":"2.2.0 - 2.2.x"},{"fix":"Use `pipx install poetry` or the official installer script to install Poetry globally in its own isolated environment. Avoid `pip install poetry` within your project's virtual environment.","message":"Do NOT install Poetry using `pip install poetry` directly into your project's virtual environment. This can lead to dependency conflicts and unintended upgrades. Poetry should be installed in an isolated environment (e.g., via `pipx` or its official installer).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review your installation workflows. If you encounter unexpected installation behavior, you can revert to the old default by setting `installer.re-resolve = true` in your Poetry configuration.","message":"The default behavior of `installer.re-resolve` changed from `true` to `false` in Poetry 2.3.0. This means Poetry now evaluates locked groups and markers to decide on package installation, rather than always re-resolving. While this makes installation clearer and faster, it might expose issues if your lock file or environment setup was previously relying on implicit re-resolution.","severity":"gotcha","affected_versions":">=2.3.0"},{"fix":"Carefully consider the versioning scheme of each dependency. For non-SemVer packages, use more precise constraints (e.g., `~=`, explicit `<` bounds) instead of `^`. Review and manually adjust constraints where necessary.","message":"The caret (`^`) operator for dependency version constraints can be a 'footgun' if applied indiscriminately, especially to packages that do not strictly follow Semantic Versioning (e.g., CalVer like `tzdata`). This can lead to either overly strict or overly lax dependency pinning, causing issues for users or maintainers.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly define your build system in `pyproject.toml` (e.g., `[build-system] requires = [\"poetry-core>=1.0.0\"] build-backend = \"poetry.core.masonry.api\"`) to ensure consistent behavior across Poetry versions.","message":"In a future minor release, Poetry will change its default behavior for projects without an explicit `[build-system]` section in `pyproject.toml`. It will fall back to `setuptools` instead of the current behavior of warning and defaulting to `poetry-core`.","severity":"deprecated","affected_versions":"Upcoming minor release after 2.3.x"},{"fix":"Review the exact command being executed that leads to this error. Ensure all necessary executables and utilities used in your build or test scripts are installed and accessible via the system's PATH. Verify that commands are correctly formatted and that arguments are not being misinterpreted as commands by the shell.","message":"A generic shell error occurred: `sh: 1: -q: not found`. This indicates that the shell (`sh`) failed to find or execute a command or argument that it interpreted as a command (in this case, '-q'). This often points to missing system dependencies, a misconfigured PATH, or an incorrectly constructed command being passed to the shell. It is not directly related to Poetry's internal logic or Python version compatibility.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review any scripts or commands executed during the test/build process for incompatible shell options. Ensure commands are compatible with the default `/bin/sh` interpreter of the target environment (e.g., `dash` on Alpine). If specific shell features are required, explicitly invoke `bash` or another compatible shell.","message":"A shell command failed with 'sh: -q: not found'. This indicates that the shell interpreter (typically /bin/sh, often `dash` on Alpine Linux) does not support the `-q` (quiet) option. This can happen if test scripts, build commands, or internal tools assume specific shell features not available in all POSIX-compliant shells.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T07:46:37.696Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Add Poetry's bin directory to your shell's configuration file (e.g., `~/.bashrc`, `~/.zshrc`, or `~/.profile`). The path is usually `~/.local/bin` or `~/.poetry/bin`. After installation, Poetry typically provides the exact `export PATH=\"...:$PATH\"` command to run. Remember to `source` your shell's config file or restart your terminal after editing.","cause":"The directory containing the Poetry executable is not included in your system's PATH environment variable, preventing your shell from finding the command.","error":"poetry: command not found"},{"fix":"Adjust the `python` version constraint in your `pyproject.toml` to be compatible with your dependencies' requirements, or use `poetry env use <python_path>` to switch to a Python interpreter that satisfies all constraints. You may need to update or downgrade specific dependencies to find a compatible set.","cause":"This error occurs when the Python version specified in your `pyproject.toml` (or the one Poetry is using) does not satisfy the Python requirements of one or more of your project's dependencies.","error":"SolverProblemError: The current project's Python requirement (...) is not compatible with some of the required packages Python requirement:"},{"fix":"Navigate to the root directory of your Poetry project (where `pyproject.toml` resides). If you are initializing a new project, run `poetry init` to create the `pyproject.toml` file. Ensure the file hasn't been accidentally deleted or renamed.","cause":"Poetry commands must be run from within a project's root directory, where the `pyproject.toml` file is located, or in a subdirectory of a project with a `pyproject.toml` in a parent directory. This error indicates Poetry cannot find this essential configuration file.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'pyproject.toml'"},{"fix":"Try clearing Poetry's cache with `poetry cache clear --all pypi`. Check your network connection. If on a headless Linux system, setting `export PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring` can bypass keyring issues (but be aware of security implications for credentials).","cause":"Slow dependency resolution can be caused by complex dependency graphs, network issues preventing efficient metadata fetching (especially for packages not fully supported by the PyPI JSON API), or problems with the system's keyring backend on certain operating systems.","error":"Poetry taking too long to resolve dependencies / dependency resolution process slow"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}