poetry-remove

Remove one or more packages from the project's dependencies

$ poetry remove [package1 package2 ...]

$ poetry remove [package] [[-D|--dev]]

$ poetry remove [package] [[-G|--group]] [group_name]

$ poetry remove [package] --dry-run

$ poetry remove [package] --lock

poetry remove [--group GROUP] [-D|--dev] [--dry-run] [--editable] <package>...

...
    The name(s) of the package(s) to be removed. Multiple packages can be specified by listing them separated by spaces.

--group GROUP
    Removes the specified dependency from a particular dependency group in pyproject.toml. If this option is not specified, the package is removed from the default production dependencies group.

-D, --dev
    A shorthand for --group dev. This option ensures the dependency is removed specifically from the development dependencies group, which typically includes tools and libraries used only during development.

--dry-run
    Executes the command in a simulation mode. It prints what actions would be performed (e.g., which files would be modified, which packages uninstalled) without actually modifying any files or uninstalling packages.

--editable
    Removes the dependency that was previously installed in editable mode (e.g., via poetry add --editable path/to/package). This option ensures proper uninstallation of such special installations.

The poetry remove command is an integral part of the Poetry dependency management system for Python projects. It facilitates the clean and efficient uninstallation of specified packages from your project. When executed, this command performs two primary actions:

First, it modifies your project's pyproject.toml file by deleting the entry for the specified dependency (or dependencies). Second, it then proceeds to uninstall the corresponding package(s) from your project's active virtual environment.

Beyond simply removing the entry from pyproject.toml, `poetry remove` also intelligently updates the poetry.lock file to reflect the change, ensuring consistency across your project's dependency graph. This makes it a crucial tool for maintaining a lean and well-defined set of project dependencies, preventing bloat and potential conflicts. It supports removing both production and development dependencies, as well as those belonging to specific custom dependency groups, providing granular control over your project's structure. Utilizing `poetry remove` helps ensure that your environment accurately mirrors your declared dependencies, promoting reproducible builds and easier project sharing.

Requires Poetry to be properly installed and configured for the project.
Carelessly removing dependencies can potentially break other packages that rely on them, leading to runtime errors.
This command only affects dependencies managed by Poetry within your project's virtual environment, not system-wide Python installations.
Always commit your pyproject.toml and poetry.lock files before and after significant dependency changes to maintain version control integrity.

When `poetry remove` is executed, it not only modifies pyproject.toml but crucially also updates the poetry.lock file. This lock file ensures that every member of your team and every deployment environment uses the exact same versions of all dependencies, making builds reproducible. Removing a package updates this file to reflect the new state of your dependencies, preventing old, uninstalled packages from being inadvertently re-installed or causing inconsistencies.

The command directly interacts with the virtual environment associated with your Poetry project. After updating pyproject.toml and poetry.lock, Poetry proceeds to uninstall the package(s) from the active virtual environment. This ensures that your local development environment is always synchronized with the dependencies declared in your project files, keeping it clean and free of orphaned packages.

The poetry remove command has been a core component of Poetry since its inception, reflecting the project's goal of providing a comprehensive and intuitive dependency management solution for Python. Its design mirrors the principles of other modern package managers, aiming to simplify operations that were historically more cumbersome with `pip` and requirements.txt files. Over the years, as Poetry itself evolved to support features like dependency groups and more robust dependency resolution, `poetry remove` has adapted to handle these complexities gracefully, offering options like --group and --dev for finer control over the project's dependency structure.

poetry add: To add new dependencies to your project., poetry install: To install all declared dependencies from poetry.lock., poetry update: To update dependencies and regenerate poetry.lock., pip uninstall: The standard Python package uninstaller, which poetry remove orchestrates within a Poetry project.