After this lesson you can install a package from the internet safely, without disturbing the rest of your computer, and you can share your project's package list with someone else.
Two kinds of modules
So far you have used your own modules and the standard library. Thousands of other useful tools are written by other people, for example for working with web requests, spreadsheets or data tables. These are called third-party packages. They are published on the Python Package Index, known as PyPI, and installed with a tool called pip.
The commands in this lesson run in a terminal, not inside Python. They are shown without output because the results depend on your computer and the network.
Checking pip
pip comes with modern Python. The safest way to run it is through the Python you intend to use:
python3 -m pip --versionWriting python3 -m pip instead of plain pip avoids a common problem where pip belongs to a different Python from the python3 you run.
Installing a package
To install, say, the popular requests package:
python3 -m pip install requestsThen you can import requests in your code. You can also install a specific version, upgrade, or remove:
python3 -m pip install requests==2.31.0
python3 -m pip install --upgrade requests
python3 -m pip uninstall requests
python3 -m pip listThe version numbers above are only an example of the syntax, so check the package page for what is current.
Why you need virtual environments
If every package goes into one shared place, projects collide. Project A may need version 1 of a package, and project B version 2. On some systems the system Python also belongs to the operating system, and changing its packages can break tools. A virtual environment solves both problems. It is a folder containing its own copy of the Python tools and its own set of installed packages, used by one project only.
Creating and activating
Inside your project folder, create an environment. The conventional name is .venv:
python3 -m venv .venvThen activate it. On macOS and Linux:
source .venv/bin/activateOn Windows PowerShell:
.venv\Scripts\Activate.ps1After activation your terminal prompt usually shows (.venv) at the start. From then on, python and pip refer to the environment. Install your packages as before and they go into .venv only. When you are finished:
deactivateYou can check from inside Python whether an environment is active. The result below was produced outside any environment, so you would see True when run inside one:
import sys
print(sys.prefix != sys.base_prefix)Falserequirements.txt
How does a friend, or a server, get the same packages? You record them in a text file. After installing what you need, export the list:
python3 -m pip freeze > requirements.txtThe file lists each package with its exact version, one per line. These two lines only illustrate the shape. Your own file will list whatever you installed:
requests==2.31.0
certifi==2023.7.22Anyone can then create their own environment and install everything at once:
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txtVersion control
The .venv folder is large and specific to one machine and operating system. Do not commit it. Add its name to your .gitignore file, and commit requirements.txt instead.
Being careful with packages
Anyone can publish to PyPI, so check a package before installing it. Look at its project page, its age, how widely it is used, and spell the name carefully, since look-alike names exist. Never run pip install with sudo, and never install a package just because a random comment told you to.
Upgrading and keeping things tidy
Packages get updated. To see which ones in your environment have newer versions, you can ask pip, and then upgrade only the ones you want:
python3 -m pip list --outdated
python3 -m pip install --upgrade requestsUpgrades can change behaviour, so after an upgrade run your program or tests before you save a new requirements.txt. If a project stops working after an update, the old file is your way back: delete the environment, create a fresh one and install from the saved list. Because an environment is cheap to rebuild, you should feel free to delete and recreate it whenever it seems confusing. That is one of the biggest practical benefits of having one per project.
Finally, install only what you need. Each extra package is more code that you depend on and must keep up to date.
Common mistakes
- Installing without activating the environment, so the package lands in the system Python.
- Using
pipandpython3from different Pythons. Usepython3 -m pip. - Committing the
.venvfolder to Git. - Forgetting to update
requirements.txtafter installing something new. - Copying a
.venvto another computer. It will not work. Recreate it from requirements.txt. - Naming your file after the package, such as
requests.py, which then shadows the real one.
Exercise
Write down, in order, the terminal commands to start a new project called shop-report that uses the requests package: create the folder, create and activate an environment, install the package, and record it in requirements.txt. Assume macOS or Linux.
Show one possible answer
mkdir shop-report
cd shop-report
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install requests
python3 -m pip freeze > requirements.txtKey points
- pip installs third-party packages from the Python Package Index (PyPI).
- A virtual environment is a private folder of packages for one project, created with python3 -m venv.
- Activate the environment before installing, so packages go into the project and not into the system Python.
- pip freeze lists installed versions, and a requirements.txt file lets anyone recreate the same setup.
- Keep the environment folder out of version control. Commit requirements.txt instead.