From d02dcd46435f9cc629000bed5df07a1a684aba7b Mon Sep 17 00:00:00 2001 From: abdullahmujahidali Date: Sun, 1 Feb 2026 18:56:47 +0500 Subject: [PATCH 1/3] 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 e5c00d4dd468b0981e3d5cd8d72fce0a5b625a1f Mon Sep 17 00:00:00 2001 From: abdullahmujahidali Date: Sun, 1 Feb 2026 19:09:41 +0500 Subject: [PATCH 2/3] 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 401dd208e1196f682cf75a42158d5bd908211c9c Mon Sep 17 00:00:00 2001 From: abdullahmujahidali Date: Mon, 9 Feb 2026 07:09:21 +0500 Subject: [PATCH 3/3] 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 %}}