poetry-sync

Sync your project's environment with the poetry.lock file

$ poetry sync

$ poetry sync --without [test|docs|...]

$ poetry sync --with [test|docs|...]

$ poetry sync --all-groups

$ poetry sync --only [test|docs|...]

$ poetry sync --only-root

$ poetry sync [[-E|--extras]]

$ poetry sync --no-root

poetry sync [OPTIONS]

-E, --extras <EXTRAS>
    Install extra feature dependencies defined in pyproject.toml. This option can be specified multiple times.

--all-extras
    Install all extra feature dependencies defined in pyproject.toml.

--only <GROUP>
    Install only dependencies from the specified group(s). This option can be specified multiple times to include multiple groups.

--without <GROUP>
    Do not install dependencies from the specified group(s). This option can be specified multiple times to exclude multiple groups.

--with <GROUP>
    Install dependencies from the specified group(s). This option can be specified multiple times to include multiple groups. Useful for optional groups not installed by default.

--sync-with-source
    Synchronize the dependencies with the defined sources in pyproject.toml and the lock file.

--dry-run
    Output the operations that would be performed, but do not execute them. Useful for previewing changes without altering the environment.

--no-dev
    Do not install development dependencies. Only main dependencies and optionally specified groups will be installed.

--no-root
    Do not install the root package (the project itself) into the virtual environment.

poetry-sync is a subcommand of the Poetry dependency management tool for Python. Its primary function is to synchronize the installed dependencies in a project's virtual environment with the exact versions specified in the poetry.lock file. This command ensures that the project's dependencies are precisely what the lock file dictates, making development environments reproducible and consistent across different machines or deployments.

Unlike poetry install, which might create or update the poetry.lock file if it's missing or outdated, poetry-sync strictly adheres to the existing lock file, installing only the packages listed there and actively removing any packages from the environment that are not present in the lock file. This 'pruning' behavior is crucial for maintaining a clean and accurate dependency environment. It's particularly useful in CI/CD pipelines to guarantee that the build environment precisely matches the committed lock file, preventing potential issues caused by mismatched or additional dependencies.

• Requires the Poetry dependency manager to be installed and available in the system's PATH.
• A valid pyproject.toml file must exist in the project root.
• A poetry.lock file must exist. poetry-sync will not create or update this file; it strictly reads from it. If the lock file is missing or outdated, consider using poetry install or poetry update first.
• Only manages dependencies for Python projects specifically configured with Poetry.

While both commands install dependencies, poetry-sync never creates or updates the poetry.lock file. Its core distinction is its 'pruning' behavior: it will actively uninstall any package from the virtual environment that is not explicitly listed in poetry.lock. poetry install, by default, will not remove unmanaged packages, although it can achieve similar behavior if passed the --sync option. poetry-sync is designed for strict environment enforcement and purity.

poetry-sync is perfect for continuous integration (CI) environments to ensure that builds are always performed with the exact dependencies defined in the committed poetry.lock file. It's also invaluable for development teams to ensure all developers are working with identical dependency sets, preventing 'works on my machine' issues. It guarantees a clean, consistent, and reproducible state for the project's dependencies, making it a cornerstone for reliable software development workflows.

The Poetry project was initiated around 2017 to offer a more robust and integrated solution for Python dependency management and packaging. Initially, poetry install served as the primary command for installing dependencies from the poetry.lock file. The poetry-sync command was introduced in later versions (specifically around Poetry 1.2 or 1.3) to provide a dedicated, explicit mechanism for strictly synchronizing the environment with the lock file. This separation of concerns made it clearer that poetry-sync's role is to ensure environmental fidelity by installing exact versions and removing extraneous packages, without altering the lock file, thus reinforcing reproducible builds and clean environments.

poetry install, poetry update, poetry add, pip install