Poetry

https://python-poetry.org/docs
Admin
Poetry is a Python tool for dependency management and packaging, simplifying project setup,...
Tokens:42,062
Snippets:667
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies with Precedence Rules

Source: https://python-poetry.org/docs/managing-dependencies

When `--with` and `--without` are used together, `--without` takes precedence. This example installs only the `test` group, as `docs` is excluded.

```bash
poetry install --with test,docs --without docs
```

--------------------------------

### Basic Dockerfile with Poetry Install

Source: https://python-poetry.org/docs/faq

This Dockerfile demonstrates a common setup where source files are copied before installing dependencies. Changes to source files can invalidate the Docker cache for the dependency installation layer.

```dockerfile
FROM python
COPY pyproject.toml poetry.lock .
COPY src/ ./src
RUN pip install poetry && poetry install --only main

```

--------------------------------

### Install Poetry from a Git repository using the installer

Source: https://python-poetry.org/docs

Install Poetry directly from a Git repository using the --git option with the installer script.

```bash
curl -sSL https://install.python-poetry.org | python3 - --git https://github.com/python-poetry/poetry.git@main

```

--------------------------------

### Install All Extras

Source: https://python-poetry.org/docs/pyproject

Use the `--all-extras` option to install all defined extras for the project.

```bash
poetry install --all-extras
```

--------------------------------

### Install Pre-commit Hooks

Source: https://python-poetry.org/docs/contributing

Installs the pre-commit tool to automatically run linting and formatting checks on code commits. This is a one-time setup.

```bash
poetry run pre-commit install
```

--------------------------------

### Install All Dependency Groups

Source: https://python-poetry.org/docs/cli

Installs all dependency groups, including optional ones, for the project.

```bash
poetry install --all-groups
```

--------------------------------

### Install Poetry Dependencies and Run Tests

Source: https://python-poetry.org/docs/contributing

Installs project dependencies using Poetry and runs the test suite. Ensure Poetry is installed and the repository is cloned locally.

```bash
poetry install
poetry run pytest
```

--------------------------------

### Install prerelease versions of Poetry

Source: https://python-poetry.org/docs

Install prerelease versions by passing the --preview flag or setting the POETRY_PREVIEW environment variable.

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

```

```bash
curl -sSL https://install.python-poetry.org | POETRY_PREVIEW=1 python3 -

```

--------------------------------

### Install Dependencies Only (No Root)

Source: https://python-poetry.org/docs/basic-usage

Use the `--no-root` flag with `poetry install` to install only the project's dependencies without installing the project itself in editable mode.

```bash
poetry install --no-root
```

--------------------------------

### Install Project Dependencies

Source: https://python-poetry.org/docs/basic-usage

Run `poetry install` to install all dependencies defined in your `pyproject.toml` file. This command ensures your project has all the necessary packages to run.

```bash
poetry install

```

--------------------------------

### Install Poetry using the official installer (Linux/macOS/WSL)

Source: https://python-poetry.org/docs

Install Poetry using the official installer script via curl and python3. This method installs Poetry in a managed virtual environment.

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

```

--------------------------------

### Install Optional Dependency Groups

Source: https://python-poetry.org/docs/managing-dependencies

Install optional dependency groups, such as 'docs', in addition to the default dependencies using the `poetry install` command with the `--with` option.

```bash
poetry install --with docs

```

--------------------------------

### Install Packages with Specific Extras

Source: https://python-poetry.org/docs/pyproject

Specify extras to install when running `poetry install` using the `-E` or `--extras` flag. Any extras not specified will be removed.

```bash
poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql
```

--------------------------------

### Install Poetry using the official installer (Windows PowerShell)

Source: https://python-poetry.org/docs

Install Poetry using the official installer script via PowerShell. This method installs Poetry in a managed virtual environment.

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

```

--------------------------------

### Install Poetry with Official Installer in CI

Source: https://python-poetry.org/docs

Install a specific version of Poetry in a CI environment using the official installer script, while setting `$POETRY_HOME` to control installation paths. This method is suitable for simpler pipelines.

```bash
export POETRY_HOME=/opt/poetry
python3 install-poetry.py --version 2.0.0
$POETRY_HOME/bin/poetry --version
```

--------------------------------

### Install a specific version of Poetry using the installer

Source: https://python-poetry.org/docs

Install a specific version of Poetry by using the --version option or setting the POETRY_VERSION environment variable.

```bash
curl -sSL https://install.python-poetry.org | python3 - --version 1.8.4

```

```bash
curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.8.4 python3 -

```

--------------------------------

### Install Project With Compiled Bytecode

Source: https://python-poetry.org/docs/cli

Installs project dependencies and compiles Python source files to bytecode during installation. This can speed up the first execution.

```bash
poetry install --compile
```

--------------------------------

### Example Plugin Registration

Source: https://python-poetry.org/docs/pyproject

An example of registering a Poetry plugin, specifying the plugin type, name, module path, and entry point.

```toml
[tool.poetry.plugins."poetry.application.plugin"]
export = "poetry_plugin_export.plugins:ExportApplicationPlugin"
```

--------------------------------

### Install additional packages for Poetry's runtime

Source: https://python-poetry.org/docs/cli

Ensures all additional packages specified are installed in the current runtime environment. This command works similarly to the `install` command but manages packages for Poetry's runtime.

```bash
poetry self install
```

--------------------------------

### Install Poetry with a custom installation directory

Source: https://python-poetry.org/docs

Set the POETRY_HOME environment variable before running the installer to specify a custom installation directory.

```bash
curl -sSL https://install.python-poetry.org | POETRY_HOME=/etc/poetry python3 -

```

--------------------------------

### Cython Example Configuration

Source: https://python-poetry.org/docs/building-extension-modules

Example pyproject.toml configuration for a project using Cython for building extensions. It specifies build requirements and includes compiled outputs in the wheel.

```toml
[build-system]
requires = ["poetry-core", "cython", "setuptools"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
... 
packages = [
    { include = "package", from = "src"},
]
include = [
    { path = "src/package/**/*.so", format = "wheel" },
]

```

--------------------------------

### Show Installed Plugins

Source: https://python-poetry.org/docs/plugins

List all currently installed plugins by running the `poetry self show plugins` command.

```bash
poetry self show plugins

```

--------------------------------

### Manual Poetry Installation with venv

Source: https://python-poetry.org/docs

Install Poetry manually using Python's `venv` module. This method provides more control and is suitable for advanced users or specific environment setups.

```bash
python3 -m venv $VENV_PATH
$VENV_PATH/bin/pip install -U pip setuptools
$VENV_PATH/bin/pip install poetry
```

--------------------------------

### Configure Build System in pyproject.toml

Source: https://python-poetry.org/docs/libraries

Define the build-system according to PEP 517 in your `pyproject.toml` file. This example uses `poetry-core` as the build backend.

```toml
[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

```

--------------------------------

### Sync with specified extras

Source: https://python-poetry.org/docs/cli

Installs project dependencies along with specified extras. Any extras not listed will be removed.

```bash
poetry sync --extras "mysql pgsql"
```

```bash
poetry sync -E mysql -E pgsql
```

```bash
poetry sync --all-extras
```

```bash
poetry sync --extras "A B"
```

--------------------------------

### Show packages in Poetry's runtime environment

Source: https://python-poetry.org/docs/cli

Lists all packages installed within the Poetry install environment. Use `--addons` to list only add-on packages.

```bash
poetry self show
```

```bash
poetry self show --addons
```

--------------------------------

### Install Plugin with pip

Source: https://python-poetry.org/docs/plugins

Install plugins using the `pip` binary located within Poetry's virtual environment. The `$POETRY_HOME` variable points to this environment.

```bash
$POETRY_HOME/bin/pip install --user poetry-plugin

```

--------------------------------

### Check Poetry Installation

Source: https://python-poetry.org/docs

Verify that Poetry has been installed correctly by checking its version. This command should be run after installation to confirm it is accessible in your PATH.

```bash
poetry --version
```

--------------------------------

### Install Poetry with pipx for CI

Source: https://python-poetry.org/docs

Install a specific version of Poetry using `pipx`, which is recommended for CI environments due to its isolation capabilities. Pinning the version ensures reproducible builds.

```bash
pipx install poetry==2.0.0
```

--------------------------------

### Install Plugin with pipx

Source: https://python-poetry.org/docs/plugins

Use the `pipx inject` command to install a plugin package into your Poetry installation if you initially installed Poetry with pipx.

```bash
pipx inject poetry poetry-plugin

```

--------------------------------

### Install Dependencies Including Optional Groups

Source: https://python-poetry.org/docs/managing-dependencies

Use the `--with` option to include specific optional dependency groups. This allows you to install only the necessary optional dependencies.

```bash
poetry install --with docs
```

--------------------------------

### Install a specific Poetry version with pipx

Source: https://python-poetry.org/docs

Install a specific version of Poetry by appending the version number to the install command.

```bash
pipx install poetry==1.8.4

```

--------------------------------

### Install Dependencies With Specific Groups

Source: https://python-poetry.org/docs/cli

Installs project dependencies, including the specified dependency groups (e.g., test, docs).

```bash
poetry install --with test,docs
```

--------------------------------

### Install Package Extras with Pip

Source: https://python-poetry.org/docs/pyproject

Extras defined in Poetry can be activated when installing the package using `pip` following PEP 508.

```bash
pip install awesome[databases]
```

--------------------------------

### Install Only Runtime Dependencies

Source: https://python-poetry.org/docs/managing-dependencies

Use `--only main` to install only the project's runtime dependencies, excluding development or other optional groups.

```bash
poetry install --only main
```

--------------------------------

### Install Python Version with Poetry

Source: https://python-poetry.org/docs/cli

Installs a specified Python version using Poetry. Use the --clean option to clean up installation if the check fails, or --free-threaded to use the free-threaded version if available.

```bash
poetry python install <PYTHON_VERSION>
```

--------------------------------

### Install Poetry with pipx

Source: https://python-poetry.org/docs

Use this command to install the latest version of Poetry globally using pipx.

```bash
pipx install poetry

```

--------------------------------

### Install Poetry from Git with pipx

Source: https://python-poetry.org/docs

Install Poetry directly from a Git repository, useful for development versions or testing pull requests. A custom suffix is used to manage these installations.

```bash
pipx install --suffix @main git+https://github.com/python-poetry/poetry.git@main
pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head

```

--------------------------------

### Install Only Specific Dependency Groups

Source: https://python-poetry.org/docs/cli

Installs only the specified dependency groups (e.g., test, docs) and no others.

```bash
poetry install --only test,docs
```

--------------------------------

### Sync only the root project

Source: https://python-poetry.org/docs/cli

Installs only the project itself without any dependencies.

```bash
poetry sync --only-root
```

--------------------------------

### Sync without installing the root project

Source: https://python-poetry.org/docs/cli

Synchronizes dependencies from the lock file but skips installing the project itself.

```bash
poetry sync --no-root
```

--------------------------------

### Display Poetry Global Help

Source: https://python-poetry.org/docs/cli

To get general help and a list of all available commands, use the `poetry help` command without any arguments.

```bash
poetry help

```

--------------------------------

### Define Optional Dependencies (Extras) in Poetry

Source: https://python-poetry.org/docs/pyproject

Use the `tool.poetry.extras` section to define optional dependency groups. These can be installed using the `--extras` flag during `poetry install`.

```toml
[tool.poetry.extras]
mysql = ["mysqlclient"]
pgsql = ["psycopg2"]
databases = ["mysqlclient", "psycopg2"]
```

--------------------------------

### Implement Application Event Handler in Plugin

Source: https://python-poetry.org/docs/plugins

This example shows how to create a plugin that listens for the COMMAND event to load environment variables from a .env file before a command executes. It filters to only load for EnvCommand types and provides debug output.

```python
from cleo.events.console_events import COMMAND
from cleo.events.console_command_event import ConsoleCommandEvent
from cleo.events.event_dispatcher import EventDispatcher
from dotenv import load_dotenv
from poetry.console.application import Application
from poetry.console.commands.env_command import EnvCommand
from poetry.plugins.application_plugin import ApplicationPlugin


class MyApplicationPlugin(ApplicationPlugin):
    def activate(self, application: Application):
        application.event_dispatcher.add_listener(
            COMMAND, self.load_dotenv
        )

    def load_dotenv(
        self, 
        event: ConsoleCommandEvent,
        event_name: str,
        dispatcher: EventDispatcher
    ) -> None:
        command = event.command
        if not isinstance(command, EnvCommand):
            return

        io = event.io

        if io.is_debug():
            io.write_line(
                "<debug>Loading environment variables.</debug>"
            )

        load_dotenv()

```

--------------------------------

### Install Only the Project Root

Source: https://python-poetry.org/docs/managing-dependencies

Use the `--only-root` option to install only the project's root dependencies, without any other groups.

```bash
poetry install --only-root
```

--------------------------------

### Configure installer.no-binary locally

Source: https://python-poetry.org/docs/configuration

Disallow binary distributions for all packages when installing locally. This is applied only when selecting which distribution for a dependency should be installed.

```bash
poetry config --local installer.no-binary :all:
```

--------------------------------

### Install Project Dependencies with Specific Python Version

Source: https://python-poetry.org/docs/managing-environments

Use this workflow when your project requires a newer Python version than your system's default. Ensure the desired Python version is installed via pyenv and then activate it for the current project before running `poetry install`.

```bash
pyenv install 3.9.8
pyenv local 3.9.8  # Activate Python 3.9 for the current project
poetry install
```

--------------------------------

### Sync all dependency groups

Source: https://python-poetry.org/docs/cli

Installs all dependency groups, including optional ones, during synchronization.

```bash
poetry sync --all-groups
```

--------------------------------

### Configure Repository via Environment Variables

Source: https://python-poetry.org/docs/repositories

Sets up a repository ('foo') and its authentication credentials using environment variables. Ensure correct suffixes are used for URL, username, and password.

```bash
export POETRY_REPOSITORIES_FOO_URL=https://pypi.example.example.org/legacy/
export POETRY_HTTP_BASIC_FOO_USERNAME=<username>
export POETRY_HTTP_BASIC_FOO_PASSWORD=<password>
```

--------------------------------

### Install Project Without Directory Dependencies

Source: https://python-poetry.org/docs/cli

Installs project dependencies but skips directory path dependencies. Useful for CI caching or Docker image builds.

```bash
poetry install --no-directory
```

--------------------------------

### Project Structure for Setuptools Build

Source: https://python-poetry.org/docs/building-extension-modules

This illustrates a typical project structure when using a setuptools-based build script for extension modules.

```text
scripts/
└── build-extension.py
src/
└── package
    ├── example.pyx
    └── __init__.py

```

--------------------------------

### Manual Poetry Installation in CI with pip

Source: https://python-poetry.org/docs

Install Poetry with maximum control in a CI environment using `pip` and `venv`. This method requires explicit commands but offers the best debugging experience and fewest external dependencies.

```bash
export POETRY_HOME=/opt/poetry
python3 -m venv $POETRY_HOME
$POETRY_HOME/bin/pip install poetry==2.0.0
$POETRY_HOME/bin/poetry --version
```

--------------------------------

### Add Dependency from Private Source

Source: https://python-poetry.org/docs/repositories

Installs a package named 'private-package' from the configured 'foo' repository.

```bash
poetry add --source foo private-package
```

--------------------------------

### Create a New Poetry Project

Source: https://python-poetry.org/docs/cli

Kicks off a new Python project with a default 'src' layout. Use `--name` to specify a different project name than the folder name, `--flat` for a flat layout, or `--name my.package` for namespace packages.

```bash
poetry new my-package

```

```bash
poetry new my-folder --name my-package

```

```bash
poetry new --flat my-package

```

```bash
poetry new --name my.package my-package

```

--------------------------------

### Get Path to Virtual Environment's Python Executable

Source: https://python-poetry.org/docs/managing-environments

Use the `--executable` option with `poetry env info` to get the specific path to the Python interpreter within the virtual environment. This is useful for running tools like mypy globally without installing them in the virtual environment.

```bash
poetry env info --executable
```

--------------------------------

### List Available Python Versions with Poetry

Source: https://python-poetry.org/docs/cli

Lists Python versions available in the environment, including installed and discovered Poetry-managed installations. Use --all to list all versions, including those available for download, or --managed to list only Poetry-managed versions.

```bash
poetry python list
```

--------------------------------

### Register GUI Scripts in pyproject.toml

Source: https://python-poetry.org/docs/pyproject

Define GUI scripts to be installed with your package. After adding or updating scripts, run 'poetry install' to make them available.

```toml
[project.gui-scripts]
my_package_gui = 'my_package.gui:run'
```

--------------------------------

### Setuptools (Cython) Build Script

Source: https://python-poetry.org/docs/building-extension-modules

Use this script to build Python extensions with Cython using setuptools. It defines compilation arguments, include directories, and libraries, then compiles the Cython files and copies the built extensions back into the project.

```python
from __future__ import annotations

import os
import shutil

from pathlib import Path

from Cython.Build import cythonize
from setuptools import Distribution
from setuptools import Extension
from setuptools.command.build_ext import build_ext


COMPILE_ARGS = ["-march=native", "-O3", "-msse", "-msse2", "-mfma", "-mfpmath=sse"]
LINK_ARGS = []
INCLUDE_DIRS = []
LIBRARIES = ["m"]


def build() -> None:
    extensions = [
        Extension(
            "*",
            ["src/package/*.pyx"],
            extra_compile_args=COMPILE_ARGS,
            extra_link_args=LINK_ARGS,
            include_dirs=INCLUDE_DIRS,
            libraries=LIBRARIES,
        )
    ]
    ext_modules = cythonize(
        extensions,
        include_path=INCLUDE_DIRS,
        compiler_directives={"binding": True, "language_level": 3},
    )

    distribution = Distribution({
        "name": "package",
        "ext_modules": ext_modules
    })

    cmd = build_ext(distribution)
    cmd.ensure_finalized()
    cmd.run()

    # Copy built extensions back to the project
    for output in cmd.get_outputs():
        output = Path(output)
        relative_extension = Path("src") / output.relative_to(cmd.build_lib)

        shutil.copyfile(output, relative_extension)
        mode = os.stat(relative_extension).st_mode
        mode |= (mode & 0o444) >> 2
        os.chmod(relative_extension, mode)


if __name__ == "__main__":
    build()

```

--------------------------------

### Tox configuration for Poetry projects (Use Case 1)

Source: https://python-poetry.org/docs/faq

Basic tox configuration for Poetry projects where dependencies are resolved by pip. This setup installs pytest and runs tests.

```ini
[tox]

[testenv]
deps =
    pytest
commands =
    pytest tests/ --import-mode importlib

```

--------------------------------

### Tox configuration for Poetry projects (Use Case 3)

Source: https://python-poetry.org/docs/faq

Tox configuration that skips the default installation step, allowing Poetry to manage all installations. Tests run against local files in editable mode.

```ini
[tox]

[testenv]
skip_install = true
allowlist_externals = poetry
commands_pre =
    poetry install
commands =
    poetry run pytest tests/ --import-mode importlib

```

--------------------------------

### Initialize a New Poetry Project Interactively

Source: https://python-poetry.org/docs/cli

Use the `poetry init` command to interactively create a `pyproject.toml` file for a new project. It prompts for necessary information and uses sensible defaults.

```bash
poetry init

```

--------------------------------

### Dependency Specification with Environment Markers

Source: https://python-poetry.org/docs/dependency-specification

Use environment markers for complex install conditions based on Python version or system platform.

```toml
[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", markers = "python_version <= '3.4' or sys_platform == 'win32'" }
```

--------------------------------

### Update Poetry to Preview Version

Source: https://python-poetry.org/docs

Install pre-release versions of Poetry by using the `--preview` flag with the self-update command. Use this if you need to test upcoming features.

```bash
poetry self update --preview
```

--------------------------------

### Sync packages in Poetry's runtime environment

Source: https://python-poetry.org/docs/cli

Ensures all additional (and no other) packages specified are installed in the current runtime environment. This command works similarly to the `sync` command but manages packages for Poetry's runtime.

```bash
poetry self sync
```

--------------------------------

### List Available Poetry Commands

Source: https://python-poetry.org/docs/cli

Use this command to display all available Poetry commands. No setup is required.

```bash
poetry list

```

--------------------------------

### Add dependency from a specific source

Source: https://python-poetry.org/docs/dependency-specification

Use the `--source` flag with `poetry add` to install a package from a pre-configured alternate repository.

```bash
poetry add my-cool-package --source foo
```

--------------------------------

### Migrated pyproject.toml using [project] with static dependencies

Source: https://python-poetry.org/docs/faq

This example demonstrates migrating to the `[project]` section with static dependencies. Note that Poetry's rich dependency specification syntax is converted to standard PEP 508 format.

```toml
[project]
name = "foobar"
version = "0.1.0"
description = ""
authors = [
    { name = "Baz Qux", email = "baz.qux@example.com" }
]
readme = "README.md"
requires-python = ">=3.13"
keywords = ["packaging", "dependency", "foobar"]
# classifiers property is dynamic because we want to create Python classifiers automatically
dynamic = ["classifiers"]
dependencies = [
    "httpx (>=0.28.1,<0.29.0)"
]

[project.urls]
homepage = "https://python-foobar.org/"
repository = "https://github.com/python-foobar/foobar"
documentation = "https://python-foobar.org/docs"

[project.scripts]
foobar = "foobar.console.application:main"

[tool.poetry]
requires-poetry = ">=2.0"
packages = [{ include = "foobar", from = "src" }]
include = [{ path = "tests", format = "sdist" }]
classifiers = [
    "Topic :: Software Development :: Build Tools",
    "Topic :: Software Development :: Libraries :: Python Modules",
]

[tool.poetry.group.dev.dependencies]
pre-commit = ">=2.10"

[tool.poetry.group.test.dependencies]
pytest = ">=8.0"

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

```

--------------------------------

### Build and Publish Package to Repository

Source: https://python-poetry.org/docs/repositories

Builds the project and publishes it to the specified repository ('foo-pub').

```bash
poetry publish --build --repository foo-pub
```

--------------------------------

### Specify Git dependency from a subdirectory

Source: https://python-poetry.org/docs/dependency-specification

To install a package located in a subdirectory of a VCS repository, use the `subdirectory` key in the `tool.poetry.dependencies` section.

```toml
subdir_package = { git = "https://github.com/myorg/mypackage_with_subdirs.git", subdirectory = "subdir" }
```

--------------------------------

### Show all available packages

Source: https://python-poetry.org/docs/cli

Lists all available packages. Pass a package name to see details for a specific package.

```bash
poetry show
```

```bash
poetry show pendulum
```

--------------------------------

### Display a Specific Configuration Setting

Source: https://python-poetry.org/docs/configuration

To view the value of a single configuration setting, provide the setting's name to the `config` command. For example, to check the virtual environments path.

```bash
poetry config virtualenvs.path
```

--------------------------------

### Add Package with Extras

Source: https://python-poetry.org/docs/cli

Specify optional features (extras) for a package, ensuring they are installed.

```bash
poetry add "requests[security,socks]"
```

```bash
poetry add "requests[security,socks]~=2.22.0"
```

```bash
poetry add "git+https://github.com/pallets/flask.git@1.1.1[dotenv,dev]"
```

--------------------------------

### List Current Poetry Configuration

Source: https://python-poetry.org/docs/cli

Use this command to display all current Poetry configuration variables. This is useful for understanding your current setup.

```bash
poetry config --list

```

--------------------------------

### Add PyTorch GPU Source and Dependencies

Source: https://python-poetry.org/docs/repositories

Example of adding an explicit package source for PyTorch GPU packages and then adding the packages using the specified source.

```bash
poetry source add --priority=explicit pytorch-gpu-src https://download.pytorch.org/whl/cu118
poetry add --source pytorch-gpu-src torch torchvision torchaudio
```

--------------------------------

### Display Help for a Specific Poetry Command

Source: https://python-poetry.org/docs/cli

To get detailed help for a specific command, such as `show`, append the command name to `poetry help`. Alternatively, use the `--help` option with the command itself.

```bash
poetry help show

```

```bash
poetry show --help

```

--------------------------------

### Show configured repository sources

Source: https://python-poetry.org/docs/cli

Displays information about all configured sources for the project. Can show all or specific sources by name.

```bash
poetry source show
```

```bash
poetry source show pypi-test
```

--------------------------------

### Dependency Specification with Extras

Source: https://python-poetry.org/docs/dependency-specification

Define dependencies that are only installed when specific extras are requested, useful for platform-specific or optional features.

```toml
[project.optional-dependencies]
paths = [
    "pathlib2 (>=2.2,<3.0) ; sys_platform == 'win32'"
]
```

--------------------------------

### Configure Basic HTTP Authentication

Source: https://python-poetry.org/docs/repositories

Set up username and password authentication for a repository. If the password is omitted, you will be prompted.

```bash
poetry config http-basic.foo <username> <password>
```

--------------------------------

### Initialize Poetry in a pre-existing project

Source: https://python-poetry.org/docs/basic-usage

Run this command within an existing project directory to create a pyproject.toml file.

```bash
cd pre-existing-project
poetry init

```

--------------------------------

### Meson Build Script Configuration

Source: https://python-poetry.org/docs/building-extension-modules

Configure Poetry to use Meson for building extensions by specifying the build script and backend in `pyproject.toml`. The build script then uses Meson to set up, compile, and install the extensions.

```toml
[tool.poetry.build]
script = "build-extension.py"

[build-system]
requires = ["poetry-core", "meson"]
build-backend = "poetry.core.masonry.api"

```

--------------------------------

### Exclusive Extras with Conditional Sources

Source: https://python-poetry.org/docs/dependency-specification

Install different package versions from specific sources based on whether an extra is specified, like CPU vs. GPU versions of a package.

```toml
[project]
name = "torch-example"
requires-python = ">=3.10"
dependencies = [
    "torch (==2.3.1+cpu) ; extra != 'cuda'",
]

[project.optional-dependencies]
cuda = [
    "torch (==2.3.1+cu118)",
]

[tool.poetry]
package-mode = false

[tool.poetry.dependencies]
torch = [
    { markers = "extra != 'cuda'", source = "pytorch-cpu"},
    { markers = "extra == 'cuda'", source = "pytorch-cuda"},
 ]

[[tool.poetry.source]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
priority = "explicit"

[[tool.poetry.source]]
name = "pytorch-cuda"
url = "https://download.pytorch.org/whl/cu118"
priority = "explicit"
```

--------------------------------

### Install Dependencies Excluding Groups

Source: https://python-poetry.org/docs/managing-dependencies

Use the `--without` option to exclude specific dependency groups during installation. This is useful for tailoring installations for different environments or build stages.

```bash
poetry install --without test,docs
```

--------------------------------

### Register Plugins using Entry Points

Source: https://python-poetry.org/docs/pyproject

Deprecated: Use `project.entry-points` instead. Register arbitrary plugins using the `tool.poetry.plugins` section, following the standard entry point format.

```toml
[tool.poetry.plugins]
"A" = {"B" = "C:D"}
```

--------------------------------

### Add Plugin with `poetry self add`

Source: https://python-poetry.org/docs/plugins

Use the `poetry self add` command to install plugins, which also checks for compatibility with your Poetry version. Note potential issues on Windows.

```bash
poetry self add poetry-plugin

```

--------------------------------

### Add a Poetry plugin

Source: https://python-poetry.org/docs/cli

Installs a Poetry plugin and makes it available at runtime. This command can also be used to upgrade Poetry's own dependencies or inject additional packages into the runtime environment.

```bash
poetry self add poetry-plugin-export
```

```bash
poetry self add poetry-core@latest
```

```bash
poetry self add artifacts-keyring
```

--------------------------------

### Specify Distribution Files in pyproject.toml

Source: https://python-poetry.org/docs/building-extension-modules

Define which files should be included in the wheel and source distributions. This example includes compiled shared objects (.so) in wheels and source files (.c) in sdists.

```toml
[tool.poetry]
... 
include = [
    { path = "package/**/*.so", format = "wheel" },
    # sources must be present in sdist, can be ignored if you only have *.pyx sources
    { path = "package/**/*.c", format = "sdist" },
]


```

--------------------------------

### List All Poetry Configuration Settings

Source: https://python-poetry.org/docs/configuration

Use the `--list` option to display all current configuration settings and their values. This is useful for understanding the current state of your Poetry environment.

```bash
poetry config --list
```

--------------------------------

### Optimized Dockerfile for Poetry Cache Busting

Source: https://python-poetry.org/docs/faq

This Dockerfile separates dependency installation from source code copying to leverage Docker's build cache more effectively. It installs third-party dependencies first, then copies source code and installs the project root.

```dockerfile
FROM python
COPY pyproject.toml poetry.lock .
RUN pip install poetry && poetry install --only main --no-root --no-directory
COPY src/ ./src
RUN poetry install --only main

```

--------------------------------

### Handle Passwords Starting with a Dash

Source: https://python-poetry.org/docs/repositories

Use double dashes to prevent passwords starting with a dash from being parsed as command-line options.

```bash
poetry config -- http-basic.pypi myUsername -myPasswordStartingWithDash
```

--------------------------------

### Configure a Publishable Repository

Source: https://python-poetry.org/docs/repositories

Use this command to configure a repository for publishing packages. Ensure the URL uses the Legacy Upload API.

```bash
poetry config repositories.testpypi https://test.pypi.org/legacy/
```

--------------------------------

### Add Simple API Repository

Source: https://python-poetry.org/docs/repositories

Configure a custom repository implementing the simple API (PEP 503) using the `poetry source add` command. Ensure the URL includes the trailing `/simple/`.

```bash
poetry source add testpypi https://test.pypi.org/simple/
```

--------------------------------

### Set Credentials via Environment Variables

Source: https://python-poetry.org/docs/repositories

Provide repository credentials using environment variables. Replace FOO with the uppercase repository name.

```bash
export POETRY_PYPI_TOKEN_FOO=my-token
```

```bash
export POETRY_HTTP_BASIC_FOO_USERNAME=<username>
```

```bash
export POETRY_HTTP_BASIC_FOO_PASSWORD=<password>
```

--------------------------------

### Register Console Scripts in pyproject.toml

Source: https://python-poetry.org/docs/pyproject

Define console scripts to be installed with your package. After adding or updating scripts, run 'poetry install' to make them available.

```toml
[project.scripts]
my_package_cli = 'my_package.console:run'
```

--------------------------------

### Build Project Archives

Source: https://python-poetry.org/docs/cli

Build source and wheel archives for the project according to PEP 517.

```bash
poetry build
```

--------------------------------

### Create a new Poetry project

Source: https://python-poetry.org/docs/basic-usage

Use this command to create a new project directory with the standard Poetry structure.

```bash
poetry new poetry-demo

```

--------------------------------

### Package Homepage Configuration (Deprecated)

Source: https://python-poetry.org/docs/pyproject

Sets the URL for the project's website. Use `project.urls` instead.

```toml
[tool.poetry]
# ...
homepage = "https://python-poetry.org/"

```

--------------------------------

### List Virtual Environments with Full Paths

Source: https://python-poetry.org/docs/cli

Use the `--full-path` option with the `env list` command to display the complete file system paths of all virtual environments associated with the current project.

```bash
poetry env list --full-path

```

--------------------------------

### Configuring Installer for Exclusive Extras

Source: https://python-poetry.org/docs/dependency-specification

Disable re-resolving for installations to ensure exclusive extras function correctly. This was a new feature in Poetry 2.0 and became default in 2.3.

```toml
poetry config installer.re-resolve false
```

--------------------------------

### Update Poetry

Source: https://python-poetry.org/docs

Update Poetry to the latest stable version using the self-update command. This is the recommended way to keep Poetry up-to-date when installed via the official installer.

```bash
poetry self update
```

--------------------------------

### Install Poetry with a custom suffix using pipx

Source: https://python-poetry.org/docs

Install different versions of Poetry in parallel by assigning a unique suffix. This is useful for testing alternate or prerelease versions.

```bash
pipx install --suffix=@1.8.4 poetry==1.8.4
poetry@1.8.4 --version

```

```bash
pipx install --suffix=@preview --pip-args=--pre poetry
poetry@preview --version

```

--------------------------------

### Uninstall Poetry with Official Installer

Source: https://python-poetry.org/docs

Remove Poetry using the official installer script with the `--uninstall` option. This method ensures a clean removal of Poetry and its associated files.

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

```bash
curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -
```

--------------------------------

### Package Description Configuration (Deprecated)

Source: https://python-poetry.org/docs/pyproject

Provides a short description for the package. Use `project.description` instead.

```toml
[tool.poetry]
# ...
description = "A short description of the package."

```

--------------------------------

### Add a new repository source

Source: https://python-poetry.org/docs/cli

Adds a new source configuration to your project. Specify the priority, name, and URL.

```bash
poetry source add --priority supplemental pypi-test https://test.pypi.org/simple/
```

```bash
poetry source add --priority=explicit pypi
```

--------------------------------

### Configure installer.build-config-settings for a package

Source: https://python-poetry.org/docs/configuration

Configure PEP 517 build settings for a specific package when a compatible binary distribution is not available. This is an experimental feature.

```bash
poetry config --local installer.build-config-settings.grpcio 
  '{"CC": "gcc", "--global-option": ["--some-global-option"], "--build-option": ["--build-option1", "--build-option2"]}'
```

--------------------------------

### Install Only Specific Dependency Groups

Source: https://python-poetry.org/docs/managing-dependencies

Use the `--only` option to install dependencies from specific groups, excluding the default set. This is useful when you need a minimal set of dependencies for a particular task.

```bash
poetry install --only docs
```

--------------------------------

### List Full Paths to Project Virtual Environments

Source: https://python-poetry.org/docs/managing-environments

To see the absolute file system paths for all virtual environments associated with the current project, use the `--full-path` option with the `poetry env list` command.

```bash
poetry env list --full-path
```

--------------------------------

### Install Multiple Poetry Versions with pipx

Source: https://python-poetry.org/docs/contributing

Use pipx to install specific versions of Poetry, including pre-releases and development branches, for testing purposes. This allows for easy switching between versions.

```bash
pipx install --suffix @1.2.1 'poetry==1.2.1'
pipx install --suffix @1.3.0rc1 'poetry==1.3.0rc1'
pipx install --suffix @main 'poetry @ git+https://github.com/python-poetry/poetry'
pipx install --suffix @local '/path/to/local/clone/of/poetry'

# now you can use any of the chosen versions of Poetry with their configured suffix, e.g.
poetry@main --version

```

```bash
pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head

```

--------------------------------

### Tox configuration for Poetry projects (Use Case 2)

Source: https://python-poetry.org/docs/faq

Tox configuration that uses Poetry to install dependencies after an initial pip install. This ensures locked dependencies are used for testing.

```ini
[tox]

[testenv]
allowlist_externals = poetry
commands_pre =
    poetry install --no-root --sync
commands =
    poetry run pytest tests/ --import-mode importlib

```

--------------------------------

### Install Dependencies Without Lock File

Source: https://python-poetry.org/docs/basic-usage

Use this command when no `poetry.lock` file exists. Poetry will resolve and install the latest compatible versions of dependencies listed in `pyproject.toml` and create a `poetry.lock` file.

```bash
poetry install
```

--------------------------------

### Configure HTTP Basic Authentication

Source: https://python-poetry.org/docs/repositories

Configures basic HTTP authentication credentials for a private repository named 'foo'. If the password is omitted, Poetry will prompt for it interactively.

```bash
poetry config http-basic.foo <username> <password>
```

```bash
poetry config http-basic.foo <username>
```

--------------------------------

### Configure Poetry Non-Package Mode

Source: https://python-poetry.org/docs/basic-usage

Set `package-mode = false` in `[tool.poetry]` to disable packaging features and only use Poetry for dependency management. This makes metadata like name and version optional and skips installing the project itself during `poetry install`.

```toml
[tool.poetry]
package-mode = false

```

--------------------------------

### Configure Repository for Publishing

Source: https://python-poetry.org/docs/repositories

Sets the upload API endpoint for a repository named 'foo' where packages will be published.

```bash
poetry config repositories.foo https://pypi.example.org/legacy/
```

--------------------------------

### Sync only specific dependency groups

Source: https://python-poetry.org/docs/cli

Installs only the specified dependency groups, ignoring others.

```bash
poetry sync --only test,docs
```

--------------------------------

### Configure credentials for Git dependencies

Source: https://python-poetry.org/docs/dependency-specification

To use HTTP basic authentication with Git repositories, configure credentials using `poetry config repositories.<name>` and `poetry config http-basic.<name>`.

```bash
poetry config repositories.git-org-project https://github.com/org/project.git
poetry config http-basic.git-org-project username token
poetry add git+https://github.com/org/project.git
```

--------------------------------

### Configure Separate Publish Repository and Credentials

Source: https://python-poetry.org/docs/repositories

Configures a distinct repository ('foo-pub') for publishing and its associated HTTP basic authentication credentials. This is recommended if publishing requires different credentials than package discovery.

```bash
poetry config repositories.foo-pub https://pypi.example.org/legacy/
poetry config http-basic.foo-pub <username> <password>
```

--------------------------------

### Exact Version Requirement

Source: https://python-poetry.org/docs/dependency-specification

Specify an exact version for a dependency to ensure only that specific version is installed.

```text
1.2.3
```

--------------------------------

### Combine Git/URL/Path with Source Repositories

Source: https://python-poetry.org/docs/dependency-specification

Use direct origin dependencies (git, url, path) to satisfy requirements, even with mutually exclusive markers. The url package can be a valid solution for a version-based requirement.

```toml
foo = [
    { platform = "darwin", url = "https://example.com/example-1.0-py3-none-any.whl" },
    { platform = "linux", version = "^1.0" },
]

```

--------------------------------

### Define Console Script

Source: https://python-poetry.org/docs/pyproject

Configure a console script that will be installed with your package. This script executes a specified function from a module.

```toml
[tool.poetry.scripts]
my_package_cli = 'my_package.console:run'

```

--------------------------------

### Specify Include Formats

Source: https://python-poetry.org/docs/pyproject

You can specify the build formats for which `include` patterns should apply.

```toml
[tool.poetry]
# ...
include = [
    { path = "tests", format = "sdist" },
    { path = "my_package/for_sdist_and_wheel.txt", format = ["sdist", "wheel"] }
]

```

--------------------------------

### Define Custom Entry Points in pyproject.toml

Source: https://python-poetry.org/docs/pyproject

Register plugins for your package using the standard entry points mechanism. This allows for arbitrary plugins discoverable via 'importlib.metadata'.

```toml
[project.entry-points]

[project.entry-points."A"]
B = "C:D"
```

```toml
[project.entry-points."poetry.application.plugin"]
export = "poetry_plugin_export.plugins:ExportApplicationPlugin"
```

--------------------------------

### Specify Package Destination Path

Source: https://python-poetry.org/docs/pyproject

Use the `to` parameter to define the relative destination path for a package upon installation.

```toml
[tool.poetry]
# ...
packages = [
    { include = "my_package", from = "lib", to = "target_package" },
]

```

--------------------------------

### Specify Editable Path in pyproject.toml

Source: https://python-poetry.org/docs/cli

Configure a local dependency to be installed in editable mode within the pyproject.toml file.

```toml
[tool.poetry.dependencies]
my-package = {path = "../my/path", develop = true}
```

--------------------------------

### Remove an addon package from Poetry's runtime

Source: https://python-poetry.org/docs/cli

Removes an installed addon package from Poetry's runtime environment.

```bash
poetry self remove poetry-plugin-export
```

--------------------------------

### Add Editable Local or VCS Dependency

Source: https://python-poetry.org/docs/cli

Install local or VCS dependencies in editable mode, reflecting changes directly.

```bash
poetry add --editable ./my-package/
```

```bash
poetry add --editable git+ssh://github.com/sdispater/pendulum.git#develop
```
Tokens:
Raw