poetry-source

Add a source configuration

$ poetry source add [source_name] [source_url]

$ poetry source add --priority [primary|supplemental|explicit] [source_name] [source_url]

$ poetry source show

$ poetry source show [source_name]

$ poetry source remove [source_name]

poetry source command [options] [arguments]

Commands:
poetry source add name url [--default|--secondary|--priority]
poetry source remove name
poetry source list
poetry source show name

add
    Adds a new package source to the project's configuration.

name (for add, remove, show)
    The unique name identifying the package source.

url (for add)
    The URL of the package repository to be added.

--default (for add)
    Designates this source as the primary default repository for all packages. Only one source can be default.

--secondary (for add)
    Designates this source as secondary. It is used to find packages only if they are not found in the default source or explicitly specified sources.

--priority (for add)
    Designates this source as priority. It is consulted before the default source for packages explicitly marked for this source or if found here first.

remove
    Removes an existing package source by its name from the project's configuration.

list
    Lists all currently configured package sources for the project, showing their names and URLs.

show
    Displays detailed information for a specific package source, including its name, URL, and type.

poetry-source is a subcommand of the Poetry Python dependency management tool, used to manage custom package sources for your project. It allows you to add, remove, list, and show details for package repositories beyond the default PyPI. This is crucial for projects relying on private package indexes, internal PyPI mirrors, or alternative public repositories.

By configuring sources, you dictate where Poetry looks for packages when resolving and installing dependencies, providing fine-grained control over your project's supply chain. It modifies the pyproject.toml file to persist source configurations, ensuring your project's dependencies are fetched from the correct locations.

poetry-source requires Poetry to be installed and accessible within your environment. Changes made by this command are saved directly to your project's pyproject.toml file, so ensure this file is version-controlled. Misconfiguring sources can lead to dependency resolution issues, where packages are not found or unexpected versions are installed. Understanding the precise order and priority of different source types (default, priority, secondary) is crucial for complex dependency management.

When Poetry attempts to resolve and install packages, it consults configured sources in a specific order: priority sources are checked first, then the default source, and finally secondary sources. If a package is explicitly configured to come from a specific source (e.g., using `poetry add package --source `), that particular source is used regardless of the general order. This hierarchical approach allows for granular control over where dependencies are fetched.

All sources configured via poetry-source are stored in the [tool.poetry.source] or [[tool.poetry.source]] sections of your project's pyproject.toml file. This ensures that the source configuration is part of your project's definition, making it portable and easily shareable across different development environments and team members.

The poetry-source command has been a fundamental part of Poetry since its early development. Poetry emerged as a modern alternative to traditional Python packaging tools, aiming to provide a more robust and deterministic approach to dependency management. The ability to manage multiple package sources was an essential feature from the start, addressing the common need for private package repositories in enterprise and open-source projects, and evolving with features like source priority and different source types to offer greater flexibility in dependency resolution.

poetry(1), poetry-install(1), poetry-add(1), pip(1)