Skip to content

Commit 4a92c36

Browse files
nathan-continonathan-contino
authored
Merge pull request #3850 from raspberrypi/more-tabs
Use tabs for virtualenv options
2 parents d51377f + 96996d6 commit 4a92c36

File tree

2 files changed

+76
-67
lines changed

2 files changed

+76
-67
lines changed

‎documentation/asciidoc/computers/os/using-python.adoc‎

Lines changed: 75 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -59,117 +59,126 @@ Python users have long dealt with conflicts between OS package managers like `ap
5959

6060
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.
6161

62-
==== Use pip with virtual environments
62+
==== Use `pip` with virtual environments
6363

64-
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.
65-
66-
Run the following command to create a virtual environment configuration folder, replacing `<env-name>` with the name you would like to use for the virtual environment (e.g. `env`):
64+
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:
6765

66+
[tabs]
67+
======
68+
per-project environments::
69+
+
70+
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:
71+
+
6872
[source,console]
6973
----
70-
$ python -m venv <env-name>
74+
$ python -m venv env
7175
----
72-
73-
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.
74-
75-
Then, execute the `bin/activate` script in the virtual environment configuration folder to enter the virtual environment:
76-
76+
+
77+
Before you work on a project, run the following command from the root of the project to start using the virtual environment:
78+
+
7779
[source,console]
7880
----
79-
$ source <env-name>/bin/activate
81+
$ source env/bin/activate
8082
----
81-
83+
+
8284
You should then see a prompt similar to the following:
83-
84-
[source,console?prompt=(<env-name>) $]
85-
----
86-
(<env-name>) $
87-
----
88-
89-
The `(<env-name>)` command prompt prefix indicates that the current terminal session is in a virtual environment named `<env-name>`.
90-
91-
To check that you're in a virtual environment, use `pip list` to view the list of installed packages:
92-
93-
[source,console?prompt=(<env-name>) $]
85+
+
86+
[source,console?prompt=(env) $]
9487
----
95-
(<env-name>) $ pip list
96-
Package Version
97-
---------- -------
98-
pip 23.0.1
99-
setuptools 66.1.1
88+
(env) $
10089
----
101-
102-
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.
103-
104-
To leave a virtual environment, run the following command:
105-
106-
[source,console?prompt=(<env-name>) $]
90+
+
91+
When you finish working on a project, run the following command from any directory to leave the virtual environment:
92+
+
93+
[source,console?prompt=(env) $]
10794
----
108-
(<env-name>) $ deactivate
95+
(env) $ deactivate
10996
----
11097
111-
==== Use a separate environment for each project
112-
113-
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:
114-
98+
per-user environments::
99+
+
100+
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.
101+
+
102+
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.
103+
+
104+
Use the following command to create a virtual environment in a hidden folder in the current user's home directory:
105+
+
115106
[source,console]
116107
----
117-
$ python -m venv env
108+
$ python -m venv ~/.env
118109
----
119-
120-
Before you work on a project, run the following command from the root of the project to start using the virtual environment:
121-
110+
+
111+
Run the following command from any directory to start using the virtual environment:
112+
+
122113
[source,console]
123114
----
124-
$ source env/bin/activate
115+
$ source ~/.env/bin/activate
125116
----
126-
117+
+
127118
You should then see a prompt similar to the following:
128-
129-
[source,console?prompt=(env) $]
119+
+
120+
[source,console?prompt=(.env) $]
130121
----
131-
(env) $
122+
(.env) $
123+
----
124+
+
125+
To leave the virtual environment, run the following command from any directory:
126+
+
127+
[source,console?prompt=(.env) $]
128+
----
129+
(.env) $ deactivate
132130
----
131+
======
133132

134-
When you finish working on a project, run the following command from any directory to leave the virtual environment:
133+
===== Create a virtual environment
135134

136-
[source,console?prompt=(env) $]
135+
Run the following command to create a virtual environment configuration folder, replacing `<env-name>` with the name you would like to use for the virtual environment (e.g. `env`):
136+
137+
[source,console]
137138
----
138-
(env) $ deactivate
139+
$ python -m venv <env-name>
139140
----
140141

141-
==== Use a separate environment for each user
142-
143-
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.
142+
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.
144143

145-
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.
144+
===== Enter a virtual environment
146145

147-
Use the following command to create a virtual environment in a hidden folder in the current user's home directory:
146+
Then, execute the `bin/activate` script in the virtual environment configuration folder to enter the virtual environment:
148147

149148
[source,console]
150149
----
151-
$ python -m venv ~/.env
150+
$ source <env-name>/bin/activate
152151
----
153152

154-
Run the following command from any directory to start using the virtual environment:
153+
You should then see a prompt similar to the following:
155154

156-
[source,console]
155+
[source,console?prompt=(<env-name>) $]
157156
----
158-
$ source ~/.env/bin/activate
157+
(<env-name>) $
159158
----
160159

161-
You should then see a prompt similar to the following:
160+
The `(<env-name>)` command prompt prefix indicates that the current terminal session is in a virtual environment named `<env-name>`.
162161

163-
[source,console?prompt=(.env) $]
162+
To check that you're in a virtual environment, use `pip list` to view the list of installed packages:
163+
164+
[source,console?prompt=(<env-name>) $]
164165
----
165-
(.env) $
166+
(<env-name>) $ pip list
167+
Package Version
168+
---------- -------
169+
pip 23.0.1
170+
setuptools 66.1.1
166171
----
167172

168-
To leave the virtual environment, run the following command from any directory:
173+
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.
169174

170-
[source,console?prompt=(.env) $]
175+
===== Exit a virtual environment
176+
177+
To leave a virtual environment, run the following command:
178+
179+
[source,console?prompt=(<env-name>) $]
171180
----
172-
(.env) $ deactivate
181+
(<env-name>) $ deactivate
173182
----
174183

175184
=== Use the Thonny editor

‎documentation/asciidoc/computers/remote-access/ssh.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Enter your account password when prompted.
6565

6666
You should now see the Raspberry Pi command prompt:
6767

68-
[source,console]
68+
[source,console?prompt=<username>@<hostname> ~ $]
6969
----
7070
<username>@<hostname> ~ $
7171
----

0 commit comments

Comments
 (0)