diff --git a/documentation/asciidoc/computers/os/using-python.adoc b/documentation/asciidoc/computers/os/using-python.adoc index 687960b3b..38dd9e20e 100644 --- a/documentation/asciidoc/computers/os/using-python.adoc +++ b/documentation/asciidoc/computers/os/using-python.adoc @@ -59,117 +59,126 @@ Python users have long dealt with conflicts between OS package managers like `ap Starting in Raspberry Pi OS _Bookworm_, packages installed via `pip` _must be installed into a Python virtual environment_ (``venv``). A virtual environment is a container where you can safely install third-party modules so they won't interfere with your system Python. -==== Use pip with virtual environments +==== Use `pip` with virtual environments -To use a virtual environment, create a container to store the environment. There are several ways you can do this depending on how you want to work with Python. - -Run the following command to create a virtual environment configuration folder, replacing `` with the name you would like to use for the virtual environment (e.g. `env`): +To use a virtual environment, create a container to store the environment. There are several ways you can do this depending on how you want to work with Python: +[tabs] +====== +per-project environments:: ++ +Many users create separate virtual environments for each Python project. Locate the virtual environment in the root folder of each project, typically with a shared name like `env`. Run the following command from the root folder of each project to create a virtual environment configuration folder: ++ [source,console] ---- -$ python -m venv +$ python -m venv env ---- - -TIP: Pass the `--system-site-packages` flag before the folder name to preload all of the currently installed packages in your system Python installation into the virtual environment. - -Then, execute the `bin/activate` script in the virtual environment configuration folder to enter the virtual environment: - ++ +Before you work on a project, run the following command from the root of the project to start using the virtual environment: ++ [source,console] ---- -$ source /bin/activate +$ source env/bin/activate ---- - ++ You should then see a prompt similar to the following: - -[source,console?prompt=() $] ----- -() $ ----- - -The `()` command prompt prefix indicates that the current terminal session is in a virtual environment named ``. - -To check that you're in a virtual environment, use `pip list` to view the list of installed packages: - -[source,console?prompt=() $] ++ +[source,console?prompt=(env) $] ---- -() $ pip list -Package Version ----------- ------- -pip 23.0.1 -setuptools 66.1.1 +(env) $ ---- - -The list should be much shorter than the list of packages installed in your system Python. You can now safely install packages with `pip`. Any packages you install with `pip` while in a virtual environment only install to that virtual environment. In a virtual environment, the `python` or `python3` commands automatically use the virtual environment's version of Python and installed packages instead of the system Python. - -To leave a virtual environment, run the following command: - -[source,console?prompt=() $] ++ +When you finish working on a project, run the following command from any directory to leave the virtual environment: ++ +[source,console?prompt=(env) $] ---- -() $ deactivate +(env) $ deactivate ---- -==== Use a separate environment for each project - -Many users create separate virtual environments for each Python project. Locate the virtual environment in the root folder of each project, typically with a shared name like `env`. Run the following command from the root folder of each project to create a virtual environment configuration folder: - +per-user environments:: ++ +Instead of creating a virtual environment for each of your Python projects, you can create a single virtual environment for your user account. **Activate that virtual environment before running any of your Python code.** This approach can be more convenient for workflows that share many libraries across projects. ++ +When creating a virtual environment for multiple projects across an entire user account, consider locating the virtual environment configuration files in your home directory. Store your configuration in a https://en.wikipedia.org/wiki/Hidden_file_and_hidden_directory#Unix_and_Unix-like_environments[folder whose name begins with a period] to hide the folder by default, preventing it from cluttering your home folder. ++ +Use the following command to create a virtual environment in a hidden folder in the current user's home directory: ++ [source,console] ---- -$ python -m venv env +$ python -m venv ~/.env ---- - -Before you work on a project, run the following command from the root of the project to start using the virtual environment: - ++ +Run the following command from any directory to start using the virtual environment: ++ [source,console] ---- -$ source env/bin/activate +$ source ~/.env/bin/activate ---- - ++ You should then see a prompt similar to the following: - -[source,console?prompt=(env) $] ++ +[source,console?prompt=(.env) $] ---- -(env) $ +(.env) $ +---- ++ +To leave the virtual environment, run the following command from any directory: ++ +[source,console?prompt=(.env) $] +---- +(.env) $ deactivate ---- +====== -When you finish working on a project, run the following command from any directory to leave the virtual environment: +===== Create a virtual environment -[source,console?prompt=(env) $] +Run the following command to create a virtual environment configuration folder, replacing `` with the name you would like to use for the virtual environment (e.g. `env`): + +[source,console] ---- -(env) $ deactivate +$ python -m venv ---- -==== Use a separate environment for each user - -Instead of creating a virtual environment for each of your Python projects, you can create a single virtual environment for your user account. **Activate that virtual environment before running any of your Python code.** This approach can be more convenient for workflows that share many libraries across projects. +TIP: Pass the `--system-site-packages` flag before the folder name to preload all of the currently installed packages in your system Python installation into the virtual environment. -When creating a virtual environment for multiple projects across an entire user account, consider locating the virtual environment configuration files in your home directory. Store your configuration in a https://en.wikipedia.org/wiki/Hidden_file_and_hidden_directory#Unix_and_Unix-like_environments[folder whose name begins with a period] to hide the folder by default, preventing it from cluttering your home folder. +===== Enter a virtual environment -Use the following command to create a virtual environment in a hidden folder in the current user's home directory: +Then, execute the `bin/activate` script in the virtual environment configuration folder to enter the virtual environment: [source,console] ---- -$ python -m venv ~/.env +$ source /bin/activate ---- -Run the following command from any directory to start using the virtual environment: +You should then see a prompt similar to the following: -[source,console] +[source,console?prompt=() $] ---- -$ source ~/.env/bin/activate +() $ ---- -You should then see a prompt similar to the following: +The `()` command prompt prefix indicates that the current terminal session is in a virtual environment named ``. -[source,console?prompt=(.env) $] +To check that you're in a virtual environment, use `pip list` to view the list of installed packages: + +[source,console?prompt=() $] ---- -(.env) $ +() $ pip list +Package Version +---------- ------- +pip 23.0.1 +setuptools 66.1.1 ---- -To leave the virtual environment, run the following command from any directory: +The list should be much shorter than the list of packages installed in your system Python. You can now safely install packages with `pip`. Any packages you install with `pip` while in a virtual environment only install to that virtual environment. In a virtual environment, the `python` or `python3` commands automatically use the virtual environment's version of Python and installed packages instead of the system Python. -[source,console?prompt=(.env) $] +===== Exit a virtual environment + +To leave a virtual environment, run the following command: + +[source,console?prompt=() $] ---- -(.env) $ deactivate +() $ deactivate ---- === Use the Thonny editor diff --git a/documentation/asciidoc/computers/remote-access/ssh.adoc b/documentation/asciidoc/computers/remote-access/ssh.adoc index acdec020d..aaa58862a 100644 --- a/documentation/asciidoc/computers/remote-access/ssh.adoc +++ b/documentation/asciidoc/computers/remote-access/ssh.adoc @@ -65,7 +65,7 @@ Enter your account password when prompted. You should now see the Raspberry Pi command prompt: -[source,console] +[source,console?prompt=@ ~ $] ---- @ ~ $ ----