Appendix C: pip and venv

Introduction

This covers creation of virtual environments and installing packages for use in your own projects. If you are using an IDE other than IDLE, chances are that your IDE has an interface for managing packages and virtual environments. The instructions that follow are intended more for people who are not using an IDE other than IDLE, or who are the DIY type, or simply those who are more interested in how Python and the Python ecosystem work. What follows is for users of Python version 3.4 or later.

PyPI, pip, and venv

There is a huge repository of modules you can use in your own projects. This repository is called PyPI—the Python Package Index—and it’s hosted at https://pypi.org/.

The Python Package Index (PyPI) is a repository of software for the Python programming language.

PyPI helps you find and install software developed and shared by the Python community.

–From the PyPI website

There you’ll find modules for just about anything—integration with cloud computing services, scientific computing, machine learning, accessing and reading web-based information, creating games, cryptography, and more. There are almost half a million projects hosted on PyPI. It’s often the case that we want to install packages hosted on PyPI, which do not ship with Python. Fortunately, there are tools that make this less challenging than it might be otherwise. Two of the most useful of these are pip and venv.

pip is the package installer for Python. You can use this to install any packages listed on PyPI. pip will manage all dependencies for you. What are dependencies? It’s often the case that one package on PyPI requires another (sometimes dozens), and each of those might require other packages. pip takes care of all that for you. pip identifies all packages that might be needed for the package you request and will automatically download and install them, usually with a single command.

The other tool presented here is venv. This is, perhaps, a little more abstract and can often confuse beginners, but in most cases it’s not too complicated. What venv does is create a virtual environment where you can install packages using pip. First, we’ll walk through the reasons behind virtual environments and how to create one using venv. Then we’ll see how to activate that virtual environment, install packages using pip, and start coding.

Of course, you can follow the directions at https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-and-using-virtual-environments and https://pip.pypa.io/en/stable/installation/, but if you want a somewhat more gentle introduction, read on.

What the heck is a virtual environment and why do I want one?

Depending on your operating system and operating system version, your computer may have come with Python installed, or Python may be installed to some protected location. Because of this, we don’t usually want to monkey with the OS-installed Python environment (in fact, doing so can break certain components of your OS). So installing packages to your OS-installed (or otherwise protected) Python environment is usually a bad idea. This is where virtual environments come in. With venv you can create an isolated Python environment for your own programming projects within which you can change Python versions, install and delete packages, etc., without ever touching your OS-installed Python environment.

Another reason you might want to use venv is to isolate and control dependencies on a project-by-project basis. Say you’re collaborating with Jane on a new game written in Python. You both want to be able to run and test your code in the same environment. With venv, again, you can create a virtual environment just for that project, and share instructions as to how to set up the environment. That way, you can ensure if your project uses package XYZ, that you and Jane both have the exact same version of package XYZ in your respective virtual environments. If you work with multiple collaborators on multiple projects, this kind of isolation and control is essential.

So that’s why we want to use venv. Virtual environments allow us to create isolated installations of Python, along with installed modules. We often create virtual environments for specific projects—so that installing or uninstalling modules for one project does not break the other project or your OS-installed Python.

A virtual environment isn’t anything magical. It’s just a directory (folder) which contains (among other things) its own version of Python, installed modules, and some utility scripts.

The venv module supports creating lightweight “virtual environments”, each with their own independent set of Python packages installed in their site directories. A virtual environment is created on top of an existing Python installation, known as the virtual environment’s “base” Python, and may optionally be isolated from the packages in the base environment, so only those explicitly installed in the virtual environment are available.

When used from within a virtual environment, common installation tools such as pip will install Python packages into a virtual environment without needing to be told to do so explicitly.

The syntax for creating a virtual environment is straightforward. At a command prompt,

$ python -m venv [name of or path to environment]

where $ represents the command prompt, and we substitute in the name of the environment we wish to create. So if we want to create a virtual environment called “cs1210” we’d use this command:

$ python -m venv cs1210

This creates a virtual environment named cs1210 in the current directory (you may wish to create your virtual environment elsewhere, but that’s up to you).

If you get an error complaining that there is no python…

On some systems, python might be named python3. If you find yourself in that situation, just substitute python3 or, on some OSs, py, for python wherever it appears in the instructions.

In order to use a virtual environment it must be activated. Once activated, any installations of modules will install the modules into the virtual environment. Python, when running in this virtual environment will have access to all installed modules.

On macOS

$ . ./cs1210/bin/activate
(cs1210) $

On Windows (with PowerShell)

PS C:\your\path\here >  .\cs1210\Scripts\activate
(cs1210) PS C:\your\path\here >

Notice that in each case after activation, the command prompt changed. The prefix, in this case (cs1210) indicates the virtual environment that is currently active.

When you’re done using a virtual environment you can deactivate it. To deactivate, use the deactivate command.

If you work in multiple virtual environments on different projects you can just deactivate one virtual environment, activate another, and off you go.

For more on virtual environments and venv see: https://docs.python.org/3/library/venv.html.

OK. I have my virtual environment activated. Now what?

Installation, upgrading, and uninstallation of third-party Python modules is done with pip. pip is an acronym for package installer for Python.

pip is the preferred installer program. Starting with Python 3.4, it is included by default with the Python binary installers.

– Python documentation

When you ask pip to install a module, it will fetch the necessary files from PyPI—the public repository of Python packages—then build and install to whatever environment is active. For example, we can use pip to install the colorama package (colorama is a module that facilitates displaying colored text).

First, before using pip make sure you have a virtual environment active. Notice that in the examples that follow, this virtual environment is called my_venv (what you call yours is up to you). Example:

(my_venv) $ pip install colorama
Collecting colorama
  Using cached colorama-0.4.6-py2.py3-none-any.whl (25 kB)
Installing collected packages: colorama
Successfully installed colorama-0.4.6

(my_venv) $

At this point, the colorama package is installed and ready for use. Pretty easy, huh?

To see what packages you have in your virtual environment you can use pip freeze. This will report all installed packages, along with dependencies and version information. You can save this information to a file and share this with others. Then all they need to do is install using this list with pip install -r <filename here> (requirements.txt is commonly used).

For more information and documentation, see: https://docs.python.org/3/installing/index.html

Original author: Clayton Cafiero < [given name] DOT [surname] AT uvm DOT edu >

No generative AI was used in producing this material. This was written the old-fashioned way.

This material is for free use under either the GNU Free Documentation License or the Creative Commons Attribution-ShareAlike 3.0 United States License (take your pick).