poetry-install

Install dependencies

$ poetry install

$ poetry install --no-root

$ poetry install --without dev

$ poetry install --with test,docs

poetry install [<options>]

--sync
    Synchronizes the project's locked dependencies with the virtual environment. This means any packages in the virtual environment that are not in poetry.lock will be uninstalled, and any missing packages will be installed.

--no-root
    Do not install the root package (the project itself) in editable mode. Useful when you only want to install dependencies without making the project itself available as a package.

--no-dev
    Do not install development dependencies. By default, development dependencies (defined in the dev group) are installed.

--only <group>
    Install only the specified dependency group(s) (space-separated). Multiple groups can be provided, e.g., --only main dev.

--without <group>
    Do not install the specified dependency group(s) (space-separated). Multiple groups can be provided, e.g., --without dev docs.

--with <group>
    Install the specified dependency group(s) (space-separated), in addition to the default dependencies. Multiple groups can be provided, e.g., --with test linters.

--extras <extra>
    Install with the specified extras (space-separated). Extras provide optional features for a package, often bringing in additional dependencies.

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

--compile
    Compile Python source files to bytecode after installation, potentially speeding up subsequent imports.

--uv
    Use uv as the backend installer for faster dependency resolution and installation. uv must be installed and available in the PATH.

The poetry install command reads the pyproject.toml file in the current directory, resolves all defined dependencies, and installs them into the project's virtual environment. If a poetry.lock file exists, Poetry will install the exact versions specified therein, ensuring deterministic builds across different environments.

If no poetry.lock file is found, poetry install will resolve the dependencies defined in pyproject.toml, install them, and then generate a new poetry.lock file. This command automatically creates and manages a virtual environment for your project if one doesn't already exist. It is a cornerstone of the Poetry workflow, enabling developers to quickly set up a project's required packages for development, testing, or deployment, while maintaining strict control over dependency versions.

Poetry Installation: This command assumes Poetry itself is already installed on your system.
Project Context: Must be run from the root directory of a Poetry project containing a pyproject.toml file.
Network Access: Requires internet access to download packages from PyPI (or configured private repositories), unless all dependencies are already cached or available locally.
Virtual Environment: While Poetry manages virtual environments, conflicts can arise if manually activated environments or conflicting Python versions are used.
Resource Usage: Dependency resolution can be CPU and memory intensive for projects with many dependencies or complex dependency graphs.

poetry install automatically detects or creates a virtual environment for your project. If no virtual environment is active or found, Poetry will create one, typically in a central location managed by Poetry or directly within the project directory (if configured with virtualenvs.in-project = true). All installed packages are isolated within this environment, preventing conflicts with global Python installations or other projects.

The poetry.lock file is crucial for deterministic builds. After poetry install resolves dependencies (or poetry lock is run), this file is generated, listing the exact versions and hashes of every package, including transitive dependencies. Subsequent runs of poetry install will use this file to install the *exact* same packages, ensuring consistency and reproducibility across all environments. It should always be committed to version control.

Poetry allows organizing dependencies into groups defined in pyproject.toml. By default, poetry install installs the main dependencies and the dev group. Options like --only, --with, and --without provide granular control over which groups are installed. This is particularly useful for distinguishing between production dependencies, development tools, testing libraries, and documentation build requirements.

Poetry emerged in 2018 as a response to the growing need for a more robust and consistent Python dependency management and packaging solution. It aimed to address shortcomings of traditional tools like pip and setup.py by introducing a single, declarative pyproject.toml file, standardizing dependency definition, and providing a powerful dependency resolver. The poetry install command has been central to its design from the beginning, offering deterministic dependency installations through the poetry.lock file, which ensures that all team members and deployment environments use the exact same package versions. Its focus on virtual environment integration and clear separation of dependency types (e.g., development vs. production) has significantly streamlined Python project workflows.

pip(1), pipenv(1), conda(1), poetry add(1), poetry update(1), poetry lock(1), poetry run(1)