/flags /poetry/poetry-install-no-root

poetry install --no-root: install dependencies without the project itself

updated 2026-10-24

tool: Poetry
command: poetry install
flag: --no-root, --only-root
default: the dependencies and the project itself (in editable mode) are installed

poetry install normally does two things: it installs the dependencies from poetry.lock and then installs the project itself in editable mode, so import myapp works. poetry install --no-root skips the second step. Use it when the source code is not there yet (the first layer of a Docker build), or when the project is not a package and Poetry fails with No file/folder found for package. For projects that will never be packaged, package-mode = false in pyproject.toml makes the flag unnecessary.

The error and the flag

The project declares a dependency but has no demo/ package directory:

bash

cat > pyproject.toml <<'EOF'
[project]
name = "demo"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["six (==1.16.0)"]
EOF
P="uvx -q poetry@2.5.1"
$P config virtualenvs.in-project true --local
echo "--- poetry install"
$P install 2>&1 | grep -E "Installing six|^Error|--no-root"
echo "--- poetry install --no-root"
$P install --no-root; echo "exit: $?"
$P run python -c "import six; print(six.__version__)"

Output

--- poetry install
  - Installing six (1.16.0)
Error: The current project could not be installed: No file/folder found for package demo
If you do not want to install the current project use --no-root.
--- poetry install --no-root
Installing dependencies from lock file

No dependencies to install or update
exit: 0
1.16.0

The plain install installs the dependency, then fails on the project itself and suggests --no-root. With the flag the run succeeds and the dependency is importable. virtualenvs.in-project only keeps the environment inside the folder; see virtualenvs.in-project.

Option or setting	What is installed
poetry install	Dependencies, then the project (editable)
--no-root	Dependencies only
--only-root	Only the project, no dependencies
--no-directory	Skip path dependencies too (Docker layers)
package-mode = false under [tool.poetry]	Never install the project; --no-root is implied
--only main / --without dev	Select dependency groups (combine with --no-root)

Docker layer caching

dockerfile

FROM python:3.13-slim
RUN pip install "poetry==2.5.1"
WORKDIR /app
ENV POETRY_VIRTUALENVS_IN_PROJECT=true
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --no-directory --only main
COPY . .
RUN poetry install --only main

The first poetry install depends only on the two metadata files, so Docker reuses the layer until dependencies change. The second call adds the project itself once the code is copied.

Pitfalls

With --no-root, poetry run myapp entry points from [project.scripts] are not installed, because they belong to the project. Install the root later or run the module with python -m.
The project's package directory must match the name (dashes become underscores) or be listed in packages; otherwise every plain install fails the same way.
--no-root does not skip dependency groups; dev dependencies are still installed unless you add --only main.
Running Poetry outside the project folder fails earlier, with Poetry could not find a pyproject.toml file.

FAQ

Should I use --no-root or package-mode = false?

If the project is never built or published (a web app, scripts, notebooks), set package-mode = false under [tool.poetry]; then poetry install never tries to install it. Use --no-root for a real package when you only want its dependencies for now, typically in a Docker layer.

Why do I get No file/folder found for package?

Poetry tries to install the project in editable mode and looks for a package directory named after the project (or the packages setting). If there is none, install the dependencies with --no-root, add the directory, or set package-mode = false.

Is there a way to install only the project and not the dependencies?

Yes, poetry install --only-root installs just the current project. It is the second half of the Docker pattern: dependencies first with --no-root, then the code with --only-root.

Sources

commands · poetrypoetry new: create a new Python project with Poetry (and poetry init)poetry new demo-app creates a project with pyproject.toml, a src-layout package, tests and README. Options like --flat and --name, poetry init and next steps.config · poetryPoetry virtualenvs.in-project: create .venv inside the projectpoetry config virtualenvs.in-project true makes Poetry create the virtualenv as .venv in the project instead of its cache. Set it with --local or an env var.errors · poetryPoetry could not find a pyproject.toml file in /path or its parentsPoetry commands need a pyproject.toml in the current folder or a parent, or fail with Poetry could not find a pyproject.toml file. Use poetry init, cd or -C.flags · poetrypoetry install --only main: skip dev dependencies (replaces --no-dev)poetry install --only main skips dev and other groups and replaces the removed --no-dev. --without, --with, optional groups, poetry sync, production installs.