diff --git a/docs/_index.md b/docs/_index.md index 13a4a60faf0..06e800ea818 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -23,18 +23,85 @@ on Linux, macOS and Windows. ## Installation +{{% warning %}} +Poetry should always be installed in a dedicated virtual environment to isolate it from the rest of your system. +In no case, it should be installed in the environment of the project that is to be managed by Poetry. +This ensures that Poetry's own dependencies will not be accidentally upgraded or uninstalled. +(Each of the following installation methods ensures that Poetry is installed into an isolated environment.) +{{% /warning %}} + {{% note %}} If you are viewing documentation for the development branch, you may wish to install a preview or development version of Poetry. See the **advanced** installation instructions to use a preview or alternate version of Poetry. {{% /note %}} -{{< tabs tabTotal="4" tabID1="installing-with-the-official-installer" tabID2="installing-with-pipx" tabID3="installing-manually" tabID4="ci-recommendations" tabName1="With the official installer" tabName2="With pipx" tabName3="Manually (advanced)" tabName4="CI recommendations">}} +{{< tabs tabTotal="4" tabID1="installing-with-pipx" tabID2="installing-with-the-official-installer" tabID3="installing-manually" tabID4="ci-recommendations" tabName1="With pipx" tabName2="With the official installer" tabName3="Manually (advanced)" tabName4="CI recommendations">}} + +{{< tab tabID="installing-with-pipx" >}} + +[`pipx`](https://github.com/pypa/pipx) is used to install Python CLI applications globally while still isolating them in virtual environments. +`pipx` will manage upgrades and uninstalls when used to install Poetry. + +{{< steps >}} +{{< step >}} +**Install Poetry** + +```bash +pipx install poetry +``` +{{< /step >}} +{{< step >}} +**Install Poetry (advanced)** + +`pipx` can install different versions of Poetry, using the same syntax as pip: + +```bash +pipx install poetry==1.2.0 +``` + +`pipx` can also install versions of Poetry in parallel, which allows for easy testing of alternate or prerelease +versions. Each version is given a unique, user-specified suffix, which will be used to create a unique binary name: + +```bash +pipx install --suffix=@1.2.0 poetry==1.2.0 +poetry@1.2.0 --version +``` + +```bash +pipx install --suffix=@preview --pip-args=--pre poetry +poetry@preview --version +``` + +Finally, `pipx` can install any valid [pip requirement spec](https://pip.pypa.io/en/stable/cli/pip_install/), which +allows for installations of the development version from `git`, or even for local testing of pull requests: + +```bash +pipx install --suffix @master git+https://github.com/python-poetry/poetry.git@master +pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head +``` + +{{< /step >}} +{{< step >}} +**Update Poetry** + +```bash +pipx upgrade poetry +``` +{{< /step >}} +{{< step >}} +**Uninstall Poetry** + +```bash +pipx uninstall poetry +``` +{{< /step >}} +{{< /steps >}} +{{< /tab >}} {{< tab tabID="installing-with-the-official-installer" >}} -We provide a custom installer that will install Poetry in a new virtual environment to isolate it -from the rest of your system. This ensures that dependencies will not be accidentally upgraded or -uninstalled, and allows Poetry to manage its own environment. +We provide a custom installer that will install Poetry in a new virtual environment +and allows Poetry to manage its own environment. {{< steps >}} {{< step >}} @@ -145,6 +212,11 @@ If you see something like `Poetry (version 1.2.0)`, your install is ready to use Poetry is able to update itself when installed using the official installer. +{{% warning %}} +Especially on Windows, `self update` may be problematic +so that a re-install with the installer should be preferred. +{{% /warning %}} + ```bash poetry self update ``` @@ -193,69 +265,6 @@ Also remove ~/.poetry/bin from your `$PATH` in your shell configuration, if it i {{< /step >}} {{< /steps >}} -{{< /tab >}} -{{< tab tabID="installing-with-pipx" >}} - -Using [`pipx`](https://github.com/pypa/pipx) to install Poetry is also possible and fully supported. - -`pipx` is used to install Python CLI applications globally while still isolating them in virtual environments. -`pipx` will manage upgrades and uninstalls when used to install Poetry. - -{{< steps >}} -{{< step >}} -**Install Poetry** - -```bash -pipx install poetry -``` -{{< /step >}} -{{< step >}} -**Install Poetry (advanced)** - -`pipx` can be install different versions of Poetry, using the same syntax as pip: - -```bash -pipx install poetry==1.2.0 -``` - -`pipx` can also install versions of Poetry in parallel, which allows for easy testing of alternate or prerelease -versions. Each version is given a unique, user-specified suffix, which will be used to create a unique binary name: - -```bash -pipx install --suffix=@1.2.0 poetry==1.2.0 -poetry@1.2.0 --version -``` - -```bash -pipx install --suffix=@preview --pip-args=--pre poetry -poetry@preview --version -``` - -Finally, `pipx` can install any valid [pip requirement spec](https://pip.pypa.io/en/stable/cli/pip_install/), which -allows for installations of the development version from `git`, or even for local testing of pull requests: - -```bash -pipx install --suffix @master git+https://github.com/python-poetry/poetry.git@master -pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head -``` - -{{< /step >}} -{{< step >}} -**Update Poetry** - -```bash -pipx upgrade poetry -``` -{{< /step >}} -{{< step >}} -**Uninstall Poetry** - -```bash -pipx uninstall poetry -``` -{{< /step >}} -{{< /steps >}} - {{< /tab >}} {{< tab tabID="installing-manually" >}} @@ -280,19 +289,34 @@ To uninstall Poetry, simply delete the entire `$VENV_PATH` directory. Unlike development environments, where making use of the latest tools is desirable, in a CI environment reproducibility should be made the priority. Here are some suggestions for installing Poetry in such an environment. -**Installation method** +**Version pinning** + +Whatever method you use, it is highly recommended to explicitly control the version of Poetry used, so that you are able +to upgrade after performing your own validation. Each install method has a different syntax for setting the version that +is used in the following examples. + +**Using pipx** + +Just as `pipx` is a powerful tool for development use, it is equally useful in a CI environment +and should be one of your top choices for use of Poetry in CI. + +```bash +pipx install poetry==1.2.0 +``` + +**Using install.python-poetry.org** +{{% note %}} The official installer script ([install.python-poetry.org](https://install.python-poetry.org)) offers a streamlined and simplified installation of Poetry, sufficient for developer use or for simple pipelines. However, in a CI environment the other two supported installation methods (pipx and manual) should be seriously considered. - -**Using install.python-poetry.org** +{{% /note %}} Downloading a copy of the installer script to a place accessible by your CI pipelines (or maintaining a copy of the [repository](https://github.com/python-poetry/install.python-poetry.org)) is strongly suggested, to ensure your pipeline's stability and to maintain control over what code is executed. -By default the installer will install to a user-specific directory. In more complex pipelines that may make accessing +By default, the installer will install to a user-specific directory. In more complex pipelines that may make accessing Poetry difficult (especially in cases like multi-stage container builds). It is highly suggested to make use of `$POETRY_HOME` when using the official installer in CI, as that way the exact paths can be controlled. @@ -302,17 +326,6 @@ python3 install-poetry.py --version 1.2.0 $POETRY_HOME/bin/poetry --version ``` -**Using pipx** - -Just as `pipx` is a powerful tool for development use, it is equally useful in a CI environment. It takes the same steps -the installer does to safely install Poetry isolated from the rest of your system, but is generic and able to do this -for any Python package, with a syntax/usage that is similar to `pip`. `pipx` should be considered equally supported in -comparison to the official installer, and should be one of your top choices for use of Poetry in CI. - -```bash -pipx install poetry==1.2.0 -``` - **Using pip (aka manually)** For maximum control in your CI environment, installation with `pip` is fully supported and something you should @@ -332,21 +345,6 @@ as the target environment managed by Poetry. If Poetry and your project are inst is likely to upgrade or uninstall its own dependencies (causing hard-to-debug and understand errors). {{% /note %}} -**Version pinning** - -Whatever method you use, it is highly recommended to explicitly control the version of Poetry used, so that you are able -to upgrade after performing your own validation. Each install method has a different syntax for setting the version -- -the following are some simple examples: - -```bash -curl -sSL https://install.python-poetry.org | python3 - --version 1.2.0 -# or -curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 - - -pipx install poetry==1.2.0 - -/path/to/venv/bin/pip install poetry==1.2.0 -``` {{< /tab >}} {{< /tabs >}} diff --git a/docs/cli.md b/docs/cli.md index 81d3f6de93d..7e4eaf4a142 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -889,6 +889,13 @@ Use of these commands will create the required `pyproject.toml` and `poetry.lock [configuration directory]({{< relref "configuration" >}}). {{% /note %}} +{{% warning %}} +Especially on Windows, `self` commands that update or remove packages may be problematic +so that other methods for installing plugins and updating Poetry are recommended. +See [Using plugins]({{< relref "plugins#using-plugins" >}}) and +[Installing Poetry]({{< relref "docs#installation" >}}) for more information. +{{% /warning %}} + ### self add The `self add` command installs Poetry plugins and make them available at runtime. Additionally, it can diff --git a/docs/plugins.md b/docs/plugins.md index 54ee7abc968..d3af23ce363 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -191,32 +191,6 @@ Installed plugin packages are automatically loaded when Poetry starts up. You have multiple ways to install plugins for Poetry -### The `self add` command - -This is the easiest way and should account for all the ways Poetry can be installed. - -```bash -poetry self add poetry-plugin -``` - -The `self add` command will ensure that the plugin is compatible with the current version of Poetry -and install the needed packages for the plugin to work. - -The package specification formats supported by the `self add` command are the same as the ones supported -by the [`add` command]({{< relref "cli#add" >}}). - -If you no longer need a plugin and want to uninstall it, you can use the `self remove` command. - -```shell -poetry self remove poetry-plugin -``` - -You can also list all currently installed plugins by running: - -```shell -poetry self show plugins -``` - ### With `pipx inject` If you used `pipx` to install Poetry you can add the plugin packages via the `pipx inject` command. @@ -250,6 +224,35 @@ If you want to uninstall a plugin, you can run: $POETRY_HOME/bin/pip uninstall poetry-plugin ``` +### The `self add` command + +{{% warning %}} +Especially on Windows, `self add` and `self remove` may be problematic +so that other methods should be preferred. +{{% /warning %}} + +```bash +poetry self add poetry-plugin +``` + +The `self add` command will ensure that the plugin is compatible with the current version of Poetry +and install the needed packages for the plugin to work. + +The package specification formats supported by the `self add` command are the same as the ones supported +by the [`add` command]({{< relref "cli#add" >}}). + +If you no longer need a plugin and want to uninstall it, you can use the `self remove` command. + +```shell +poetry self remove poetry-plugin +``` + +You can also list all currently installed plugins by running: + +```shell +poetry self show plugins +``` + ## Maintaining a plugin