Skip to content

Commit

Permalink
docs: update _index.md
Browse files Browse the repository at this point in the history
  • Loading branch information
finswimmer committed Nov 27, 2024
1 parent 2d6c5b2 commit d0418bc
Showing 1 changed file with 20 additions and 48 deletions.
68 changes: 20 additions & 48 deletions docs/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,24 +18,11 @@ Poetry offers a lockfile to ensure repeatable installs, and can build your proje

## System requirements

Poetry requires **Python 3.8+**. It is multi-platform and the goal is to make it work equally well
Poetry requires **Python 3.9+**. It is multi-platform and the goal is to make it work equally well
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.
It should in no case 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.)
In addition, the isolated virtual environment in which poetry is installed should not be activated for running poetry commands.
{{% /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-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" >}}
Expand Down Expand Up @@ -71,14 +58,14 @@ source, having multiple versions installed at the same time etc.
`pipx` can install different versions of Poetry, using the same syntax as pip:

```bash
pipx install poetry==1.2.0
pipx install poetry==1.8.4
```

`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
pipx install --suffix=@1.8.4 poetry==1.8.4
[email protected] --version
```

Expand Down Expand Up @@ -127,22 +114,12 @@ and is developed in [its own repository](https://github.com/python-poetry/instal
The script can be executed directly (i.e. 'curl python') or downloaded and then executed from disk
(e.g. in a CI environment).

{{% warning %}}
The `install-poetry.py` installer has been deprecated and removed from the Poetry repository.
Please migrate from the in-tree version to the standalone version described above.
{{% /warning %}}

**Linux, macOS, Windows (WSL)**

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

{{% note %}}
Note: On some systems, `python` may still refer to Python 2 instead of Python 3. We always suggest the
`python3` binary to avoid ambiguity.
{{% /note %}}

**Windows (Powershell)**
```powershell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
Expand Down Expand Up @@ -187,8 +164,8 @@ Similarly, if you want to install a specific version, you can use `--version` op
environment variable:

```bash
curl -sSL https://install.python-poetry.org | python3 - --version 1.2.0
curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 -
curl -sSL https://install.python-poetry.org | python3 - --version 1.8.4
curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.8.4 python3 -
```

You can also install Poetry from a `git` repository by using the `--git` option:
Expand Down Expand Up @@ -254,14 +231,9 @@ And finally, if you want to install a specific version, you can pass it as an ar
to `self update`.

```bash
poetry self update 1.2.0
poetry self update 1.8.4
```

{{% warning %}}
Poetry `1.1` series releases are not able to update in-place to `1.2` or newer series releases.
To migrate to newer releases, uninstall using your original install method, and then reinstall
using the [methods above]({{< ref "#installation" >}} "Installation").
{{% /warning %}}
{{< /step >}}
{{< step >}}
**Uninstall Poetry**
Expand All @@ -274,17 +246,6 @@ the `POETRY_UNINSTALL` environment variable before executing the installer.
curl -sSL https://install.python-poetry.org | python3 - --uninstall
curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -
```
{{% warning %}}
If you installed using the deprecated `get-poetry.py` script, you should remove the path it uses manually, e.g.
```bash
rm -rf "${POETRY_HOME:-~/.poetry}"
```
Also remove ~/.poetry/bin from your `$PATH` in your shell configuration, if it is present.
{{% /warning %}}
{{< /step >}}
{{< /steps >}}
Expand Down Expand Up @@ -324,7 +285,7 @@ Just as `pipx` is a powerful tool for development use, it is equally useful in a
and should be one of your top choices for use of Poetry in CI.
```bash
pipx install poetry==1.2.0
pipx install poetry==2.0.0
```
**Using install.python-poetry.org**
Expand All @@ -345,7 +306,7 @@ Poetry difficult (especially in cases like multi-stage container builds). It is

```bash
export POETRY_HOME=/opt/poetry
python3 install-poetry.py --version 1.2.0
python3 install-poetry.py --version 2.0.0
$POETRY_HOME/bin/poetry --version
```

Expand All @@ -358,7 +319,7 @@ best debugging experience, and leaves you subject to the fewest external tools.
```bash
export POETRY_HOME=/opt/poetry
python3 -m venv $POETRY_HOME
$POETRY_HOME/bin/pip install poetry==1.2.0
$POETRY_HOME/bin/pip install poetry==2.0.0
$POETRY_HOME/bin/poetry --version
```

Expand All @@ -371,7 +332,18 @@ is likely to upgrade or uninstall its own dependencies (causing hard-to-debug an
{{< /tab >}}
{{< /tabs >}}

{{% warning %}}
Poetry should always be installed in a dedicated virtual environment to isolate it from the rest of your system.
It should in no case 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.)
In addition, the isolated virtual environment in which poetry is installed should not be activated for running poetry commands.
{{% /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 %}}
## Enable tab completion for Bash, Fish, or Zsh
Expand Down

0 comments on commit d0418bc

Please sign in to comment.