Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix basic usage docs about environment activation #9963

Merged
merged 2 commits into from
Jan 6, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 2 additions & 36 deletions docs/basic-usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ To run your script simply use `poetry run python your_script.py`.
Likewise if you have command line tools such as `pytest` or `black` you can run them using `poetry run pytest`.

{{% note %}}
If managing your own virtual environment externally, you do not need to use `poetry run` or `poetry shell` since
If managing your own virtual environment externally, you do not need to use `poetry run` since
you will, presumably, already have activated that virtual environment and made available the correct python instance.
For example, these commands should output the same python path:

Expand All @@ -191,41 +191,7 @@ which python

### Activating the virtual environment

The easiest way to activate the virtual environment is to create a nested shell with `poetry shell`.

To deactivate the virtual environment and exit this new shell type `exit`.
To deactivate the virtual environment without leaving the shell use `deactivate`.

{{% note %}}
**Why a nested shell?**

Child processes inherit their environment from their parents, but do not share
them. As such, any modifications made by a child process is not persisted after
the child process exits. A Python application (Poetry), being a child process,
cannot modify the environment of the shell that it has been called from such
that an activated virtual environment remains active after the Poetry command
has completed execution.

Therefore, Poetry has to create a sub-shell with the virtual environment activated
in order for the subsequent commands to run from within the virtual environment.
{{% /note %}}

If you'd like to prevent `poetry shell` from modifying your shell prompt on virtual environment activation, you should
set `VIRTUAL_ENV_DISABLE_PROMPT=1` as an environment variable before running the command.

Alternatively, to avoid creating a new shell, you can manually activate the
virtual environment by running `source {path_to_venv}/bin/activate` (`{path_to_venv}\Scripts\activate.ps1` in PowerShell).
To get the path to your virtual environment run `poetry env info --path`.
You can also combine these into a one-liner, such as `source $(poetry env info --path)/bin/activate`
(`& ((poetry env info --path) + "\Scripts\activate.ps1")` in Powershell).

To deactivate this virtual environment simply use `deactivate`.

| | POSIX Shell | Windows (PowerShell) | Exit/Deactivate |
| ----------------- | ----------------------------------------------- | -------------------------------------------------------- | --------------- |
| Sub-shell | `poetry shell` | `poetry shell` | `exit` |
| Manual Activation | `source {path_to_venv}/bin/activate` | `{path_to_venv}\Scripts\activate.ps1` | `deactivate` |
| One-liner | `source $(poetry env info --path)/bin/activate` | `& ((poetry env info --path) + "\Scripts\activate.ps1")` | `deactivate` |
See [Activating the virtual environment]({{< relref "managing-environments#activating-the-environment" >}}).

## Version constraints

Expand Down
Loading