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 avirtual 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 install the Python version from whichthe command was run (as reported by the--version option).For instance, executing the command withpython3.12 will installversion 3.12.

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

python-mvenvtutorial-env

This will create thetutorial-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.

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 virtual environment will change your shell’s prompt to show whatvirtual environment you’re using, and modify the environment so that runningpython will get you that particular version and installation of Python.For example:

$source~/envs/tutorial-env/bin/activate(tutorial-env)$pythonPython3.5.1(default,May62016,10:59:36)...>>>importsys>>>sys.path['','/usr/local/lib/python35.zip',...,'~/envs/tutorial-env/lib/python3.5/site-packages']>>>

To deactivate a virtual environment, type:

deactivate

into the terminal.

12.3.Managing Packages with pip¶

You can install, upgrade, and remove packages using a program calledpip. By defaultpip will install packages from thePythonPackage 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 theInstalling Python Modules guide forcomplete documentation forpip.)

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

(tutorial-env)$python-mpipinstallnovasCollectingnovasDownloadingnovas-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:

(tutorial-env)$python-mpipinstallrequests==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 runpython-mpipinstall--upgrade to upgrade the package to the latest version:

(tutorial-env)$python-mpipinstall--upgraderequestsCollectingrequestsInstallingcollectedpackages:requestsFoundexistinginstallation:requests2.6.0Uninstallingrequests-2.6.0:Successfullyuninstalledrequests-2.6.0Successfullyinstalledrequests-2.7.0

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

python-mpipshow will display information about a particular package:

(tutorial-env)$python-mpipshowrequests---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:

python-mpiplist will display all of the packages installed inthe virtual environment:

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

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

(tutorial-env)$python-mpipfreeze>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:

(tutorial-env)$python-mpipinstall-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 thePython packaging user guide.