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 avirtualenvironment (often shortened to “virtualenv”), a self-containeddirectory tree that contains a Python installation for a particularversion 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 virtualenv 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 script used to create and manage virtual environments is calledpyvenv.pyvenv will usually install the mostrecent version of Python that you have available; the script is alsoinstalled with a version number, so if you have multiple versions ofPython on your system you can select a specific Python version byrunningpyvenv-3.4 or whichever version you want.

To create a virtualenv, decide upon a directorywhere you want to place it and runpyvenv with thedirectory path:

pyvenvtutorial-env

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

Once you’ve created a virtual environment, you need toactivate it.

On Windows, run:

tutorial-env/Scripts/activate

On Unix or MacOS, run:

sourcetutorial-env/bin/activate

(This script is written for the bash shell. If you use thecsh orfish shells, there are alternateactivate.csh andactivate.fish scripts you should useinstead.)

Activating the virtualenv will change your shell’s prompt to show whatvirtualenv you’re using, and modify the environment so that runningpython will get you that particular version and installation ofPython. For example:

->source~/envs/tutorial-env/bin/activate(tutorial-env)->pythonPython3.4.3+(3.4:c7b9645a6f35+,May222015,09:31:25)...>>>importsys>>>sys.path['','/usr/local/lib/python34.zip',...,'~/envs/tutorial-env/lib/python3.4/site-packages']>>>

12.3. Managing Packages with pip¶

Once you’ve activated a virtual environment, you can install, upgrade,and remove packages using a program calledpip. By defaultpip will install packages from the Python Package Index,<https://pypi.python.org/pypi>. You can browse the Python Package Indexby going to it in your web browser, or you can usepip’slimited search feature:

(tutorial-env)->pipsearchastronomyskyfield-ElegantastronomyforPythongary-Galacticastronomyandgravitationaldynamics.novas-TheUnitedStatesNavalObservatoryNOVASastronomylibraryastroobs-ProvidesastronomyephemeristoplantelescopeobservationsPyAstronomy-AcollectionofastronomyrelatedtoolsforPython....

pip has a number of subcommands: “search”, “install”, “uninstall”,“freeze”, etc. (Consult theInstalling Python Modules guide forcomplete documentation forpip.)

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

->pipinstallnovasCollectingnovasDownloadingnovas-3.1.1.3.tar.gz(136kB)Installingcollectedpackages:novasRunningsetup.pyinstallfornovasSuccessfullyinstallednovas-3.1.1.3

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

->pipinstallrequests==2.6.0Collectingrequests==2.6.0Usingcachedrequests-2.6.0-py2.py3-none-any.whlInstallingcollectedpackages:requestsSuccessfullyinstalledrequests-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 runpipinstall--upgrade to upgrade the package to the latest version:

->pipinstall--upgraderequestsCollectingrequestsInstallingcollectedpackages:requestsFoundexistinginstallation:requests2.6.0Uninstallingrequests-2.6.0:Successfullyuninstalledrequests-2.6.0Successfullyinstalledrequests-2.7.0

pipuninstall followed by one or more package names will remove thepackages from the virtual environment.

pipshow will display information about a particular package:

(tutorial-env)->pipshowrequests---Metadata-Version:2.0Name:requestsVersion:2.7.0Summary:PythonHTTPforHumans.Home-page:http://python-requests.orgAuthor:KennethReitzAuthor-email:me@kennethreitz.comLicense:Apache2.0Location:/Users/akuchling/envs/tutorial-env/lib/python3.4/site-packagesRequires:

piplist will display all of the packages installed in the virtualenvironment:

(tutorial-env)->piplistnovas(3.1.1.3)numpy(1.9.2)pip(7.0.3)requests(2.7.0)setuptools(16.0)

pipfreeze will produce a similar list of the installed packages,but the output uses the format thatpipinstall expects.A common convention is to put this list in arequirements.txt file:

(tutorial-env)->pipfreeze>requirements.txt(tutorial-env)->catrequirements.txtnovas==3.1.1.3numpy==1.9.2requests==2.7.0

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

->pipinstall-rrequirements.txtCollectingnovas==3.1.1.3(from-rrequirements.txt(line1))...Collectingnumpy==1.9.2(from-rrequirements.txt(line2))...Collectingrequests==2.7.0(from-rrequirements.txt(line3))...Installingcollectedpackages:novas,numpy,requestsRunningsetup.pyinstallfornovasSuccessfullyinstallednovas-3.1.1.3numpy-1.9.2requests-2.7.0

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