You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: documentation/asciidoc/computers/os/using-python.adoc
+75-66Lines changed: 75 additions & 66 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -59,117 +59,126 @@ Python users have long dealt with conflicts between OS package managers like `ap
59
59
60
60
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.
61
61
62
-
==== Use pip with virtual environments
62
+
==== Use `pip` with virtual environments
63
63
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:
67
65
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
+
+
68
72
[source,console]
69
73
----
70
-
$ python -m venv <env-name>
74
+
$ python -m venv env
71
75
----
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
+
+
77
79
[source,console]
78
80
----
79
-
$ source <env-name>/bin/activate
81
+
$ source env/bin/activate
80
82
----
81
-
83
+
+
82
84
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) $]
94
87
----
95
-
(<env-name>) $ pip list
96
-
Package Version
97
-
---------- -------
98
-
pip 23.0.1
99
-
setuptools 66.1.1
88
+
(env) $
100
89
----
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) $]
107
94
----
108
-
(<env-name>) $ deactivate
95
+
(env) $ deactivate
109
96
----
110
97
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
+
+
115
106
[source,console]
116
107
----
117
-
$ python -m venv env
108
+
$ python -m venv ~/.env
118
109
----
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
+
+
122
113
[source,console]
123
114
----
124
-
$ source env/bin/activate
115
+
$ source ~/.env/bin/activate
125
116
----
126
-
117
+
+
127
118
You should then see a prompt similar to the following:
128
-
129
-
[source,console?prompt=(env) $]
119
+
+
120
+
[source,console?prompt=(.env) $]
130
121
----
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
132
130
----
131
+
======
133
132
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
135
134
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]
137
138
----
138
-
(env) $ deactivate
139
+
$ python -m venv <env-name>
139
140
----
140
141
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.
144
143
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
146
145
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:
148
147
149
148
[source,console]
150
149
----
151
-
$ python -m venv ~/.env
150
+
$ source <env-name>/bin/activate
152
151
----
153
152
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:
155
154
156
-
[source,console]
155
+
[source,console?prompt=(<env-name>) $]
157
156
----
158
-
$ source ~/.env/bin/activate
157
+
(<env-name>) $
159
158
----
160
159
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>`.
162
161
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>) $]
164
165
----
165
-
(.env) $
166
+
(<env-name>) $ pip list
167
+
Package Version
168
+
---------- -------
169
+
pip 23.0.1
170
+
setuptools 66.1.1
166
171
----
167
172
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.
169
174
170
-
[source,console?prompt=(.env) $]
175
+
===== Exit a virtual environment
176
+
177
+
To leave a virtual environment, run the following command:
0 commit comments