12. Virtual Environments and Packages (2024)

12.1. Introduction¶

Python applications will often use packages and modules that don’tcome as part of the standard library. Applications will sometimesneed a specific version of a library, because the application mayrequire that a particular bug has been fixed or the application may bewritten using an obsolete version of the library’s interface.

This means it may not be possible for one Python installation to meetthe requirements of every application. If application A needs version1.0 of a particular module but application B needs version 2.0, thenthe requirements are in conflict and installing either version 1.0 or 2.0will leave one application unable to run.

The solution for this problem is to create a virtual environment, aself-contained directory tree that contains a Python installation for aparticular version of Python, plus a number of additional packages.

Different applications can then use different virtual environments.To resolve the earlier example of conflicting requirements,application A can have its own virtual environment with version 1.0installed while application B has another virtual environment with version 2.0.If application B requires a library be upgraded to version 3.0, this willnot affect application A’s environment.

12.2. Creating Virtual Environments¶

The module used to create and manage virtual environments is calledvenv. venv will usually install the most recent version ofPython that you have available. If you have multiple versions of Python on yoursystem, you can select a specific Python version by running python3 orwhichever version you want.

To create a virtual environment, decide upon a directory where you want toplace it, and run the venv module as a script with the directory path:

python -m venv tutorial-env

This will create the tutorial-env directory if it doesn’t exist,and also create directories inside it containing a copy of the Pythoninterpreter and various supporting files.

A common directory location for a virtual environment is .venv.This name keeps the directory typically hidden in your shell and thusout of the way while giving it a name that explains why the directoryexists. It also prevents clashing with .env environment variabledefinition files that some tooling supports.

Once you’ve created a virtual environment, you may activate it.

12.3. Managing Packages with pip¶

You can install, upgrade, and remove packages using a program calledpip. By default pip will install packages from the PythonPackage Index. You can browse the PythonPackage Index by going to it in your web browser.

pip has a number of subcommands: “install”, “uninstall”,“freeze”, etc. (Consult the Installing Python Modules guide forcomplete documentation for pip.)

You can install the latest version of a package by specifying a package’s name:

(tutorial-env) $ python -m pip install novasCollecting novas Downloading novas-3.1.1.3.tar.gz (136kB)Installing collected packages: novas Running setup.py install for novasSuccessfully installed novas-3.1.1.3

You can also install a specific version of a package by giving thepackage name followed by == and the version number:

(tutorial-env) $ python -m pip install requests==2.6.0Collecting requests==2.6.0 Using cached requests-2.6.0-py2.py3-none-any.whlInstalling collected packages: requestsSuccessfully installed requests-2.6.0

If you re-run this command, pip will notice that the requestedversion is already installed and do nothing. You can supply adifferent version number to get that version, or you can run python-m pip install --upgrade to upgrade the package to the latest version:

(tutorial-env) $ python -m pip install --upgrade requestsCollecting requestsInstalling collected packages: requests Found existing installation: requests 2.6.0 Uninstalling requests-2.6.0: Successfully uninstalled requests-2.6.0Successfully installed requests-2.7.0

python -m pip uninstall followed by one or more package names willremove the packages from the virtual environment.

python -m pip show will display information about a particular package:

(tutorial-env) $ python -m pip show requests---Metadata-Version: 2.0Name: requestsVersion: 2.7.0Summary: Python HTTP for Humans.Home-page: http://python-requests.orgAuthor: Kenneth ReitzAuthor-email: me@kennethreitz.comLicense: Apache 2.0Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packagesRequires:

python -m pip list will display all of the packages installed inthe virtual environment:

(tutorial-env) $ python -m pip listnovas (3.1.1.3)numpy (1.9.2)pip (7.0.3)requests (2.7.0)setuptools (16.0)

python -m pip freeze will produce a similar list of the installed packages,but the output uses the format that python -m pip install expects.A common convention is to put this list in a requirements.txt file:

(tutorial-env) $ python -m pip freeze > requirements.txt(tutorial-env) $ cat requirements.txtnovas==3.1.1.3numpy==1.9.2requests==2.7.0

The requirements.txt can then be committed to version control andshipped as part of an application. Users can then install all thenecessary packages with install -r:

(tutorial-env) $ python -m pip install -r requirements.txtCollecting novas==3.1.1.3 (from -r requirements.txt (line 1)) ...Collecting numpy==1.9.2 (from -r requirements.txt (line 2)) ...Collecting requests==2.7.0 (from -r requirements.txt (line 3)) ...Installing collected packages: novas, numpy, requests Running setup.py install for novasSuccessfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0

pip has many more options. Consult the Installing Python Modulesguide for complete documentation for pip. When you’ve writtena package and want to make it available on the Python Package Index,consult the Python packaging user guide.