From 44c5886a069077e200204d8066fa7abdc86b8574 Mon Sep 17 00:00:00 2001 From: abdullahmujahidali Date: Sun, 1 Feb 2026 18:56:47 +0500 Subject: [PATCH 1/4] docs: clarify install vs update command differences --- docs/cli.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/cli.md b/docs/cli.md index db9e28be603..7c138d248b5 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -475,6 +475,14 @@ poetry init The `install` command reads the `pyproject.toml` file from the current project, resolves the dependencies, and installs them. +{{% note %}} +**When to use `install` vs `update`:** +- Use `poetry install` to install dependencies as specified in `poetry.lock` (or resolve and create it if missing). + This is what you run after cloning a project or when you want reproducible installs. +- Use `poetry update` when you want to update dependencies to their latest versions (within constraints) + and refresh `poetry.lock`. +{{% /note %}} + {{% note %}} Normally, you should prefer `poetry sync` to `poetry install` to avoid untracked outdated packages. However, if you have set `virtualenvs.create = false` to install dependencies into your system environment, @@ -1276,7 +1284,14 @@ you should use the `update` command. poetry update ``` -This will resolve all dependencies of the project and write the exact versions into `poetry.lock`. +This will resolve all dependencies of the project, write the exact versions into `poetry.lock`, +and install them into your environment. + +{{% note %}} +The `update` command **does not** modify your `pyproject.toml` file. It only updates the +`poetry.lock` file with the latest compatible versions based on the constraints already +defined in `pyproject.toml`. To change version constraints, use the `add` command instead. +{{% /note %}} If you just want to update a few packages and not all, you can list them as such: From 5866f5ee42aa41d9db259ce86befe262760dd4ea Mon Sep 17 00:00:00 2001 From: abdullahmujahidali Date: Sun, 1 Feb 2026 19:09:41 +0500 Subject: [PATCH 2/4] docs: clarify wording per review feedback --- docs/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli.md b/docs/cli.md index 7c138d248b5..fdd516f82f4 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -477,7 +477,7 @@ resolves the dependencies, and installs them. {{% note %}} **When to use `install` vs `update`:** -- Use `poetry install` to install dependencies as specified in `poetry.lock` (or resolve and create it if missing). +- Use `poetry install` to install dependencies as specified in `poetry.lock` (or resolve dependencies and create the lock file if it's missing). This is what you run after cloning a project or when you want reproducible installs. - Use `poetry update` when you want to update dependencies to their latest versions (within constraints) and refresh `poetry.lock`. From 913d9a9c9553d0a643b5ffb7ab12ced1d0f8a6c8 Mon Sep 17 00:00:00 2001 From: abdullahmujahidali Date: Mon, 9 Feb 2026 07:09:21 +0500 Subject: [PATCH 3/4] docs: mention poetry sync for reproducible installs and clarify constraints --- docs/cli.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index fdd516f82f4..15936c5c8a6 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -478,8 +478,9 @@ resolves the dependencies, and installs them. {{% note %}} **When to use `install` vs `update`:** - Use `poetry install` to install dependencies as specified in `poetry.lock` (or resolve dependencies and create the lock file if it's missing). - This is what you run after cloning a project or when you want reproducible installs. -- Use `poetry update` when you want to update dependencies to their latest versions (within constraints) + This is what you run after cloning a project. For reproducible installs, prefer `poetry sync`, + which also removes packages that are not in the lock file. +- Use `poetry update` when you want to update dependencies to their latest versions (within the constraints from the `pyproject.toml`) and refresh `poetry.lock`. {{% /note %}} From 3b9b705e0fbd2f87d2531da011622c29af48eecf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Randy=20D=C3=B6ring?= <30527984+radoering@users.noreply.github.com> Date: Sat, 14 Feb 2026 10:08:14 +0100 Subject: [PATCH 4/4] move notes a bit down --- docs/cli.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 15936c5c8a6..29d5ff14d73 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -475,9 +475,19 @@ poetry init The `install` command reads the `pyproject.toml` file from the current project, resolves the dependencies, and installs them. +```bash +poetry install +``` + +If there is a `poetry.lock` file in the current directory, +it will use the exact versions from there instead of resolving them. +This ensures that everyone using the library will get the same versions of the dependencies. + +If there is no `poetry.lock` file, Poetry will create one after dependency resolution. + {{% note %}} **When to use `install` vs `update`:** -- Use `poetry install` to install dependencies as specified in `poetry.lock` (or resolve dependencies and create the lock file if it's missing). +- Use `poetry install` to install dependencies as specified in `poetry.lock` (or resolve dependencies and create the lock file if it is missing). This is what you run after cloning a project. For reproducible installs, prefer `poetry sync`, which also removes packages that are not in the lock file. - Use `poetry update` when you want to update dependencies to their latest versions (within the constraints from the `pyproject.toml`) @@ -492,16 +502,6 @@ system site-packages available in your virtual environment, you should use `poet because `poetry sync` will normally not work well in these cases. {{% /note %}} -```bash -poetry install -``` - -If there is a `poetry.lock` file in the current directory, -it will use the exact versions from there instead of resolving them. -This ensures that everyone using the library will get the same versions of the dependencies. - -If there is no `poetry.lock` file, Poetry will create one after dependency resolution. - If you want to exclude one or more dependency groups for the installation, you can use the `--without` option.