Finding Modules: The Path
For modules to be available for use, the Python interpreter must
be able to locate the module file. Python has a set of directories in
which it looks for module files. This set of directories is called the
search path, and is analogous to the
PATH environment variable used by an operating system to
locate an executable file.
Python's search path is built from a number of sources:
-
PYTHONHOME is used to define directories that
are part of the Python installation. If this environment variable is
not defined, then a standard directory structure is used. For
Windows, the standard location is based on the directory into which
Python is installed. For most Linux environments, Python is
installed under /usr/local, and the libraries
can be found there. For Mac OS, the home directory is under
/Library/Frameworks/Python.framework.
-
PYTHONPATH is used to add directories to the
path. This environment variable is formatted like the OS
PATH variable, with a series of filenames separated
by :'s (or ;'s for Windows).
-
Script Directory. If you run a Python script, that script's
directory is placed first on the search path so that locally-defined
moules will be used instead of built-in modules of the same
name.
-
The site module's locations are also
added. (This can be disabled by starting Python with the
-S option.) The site module will
use the PYTHONHOME location(s) to create up to four
additional directories. Generally, the most interesting one is the
site-packages directory. This directory is a
handy place to put additional modules you've downloaded.
Additionally, this directory can contain .PTH
files. The site module reads
.PTH files and puts the named directories onto
the search path.
The search path is defined by the path variable
in the sys module. If we import sys,
we can display sys.path. This is very handy for
debugging. When debugging shell scripts, it can help to run
'python -c 'import sys; print sys.path' just to see parts
of the Python environment settings.
Installing a module, then, is a matter of assuring that the module
appears on the search path. There are four central methods for doing
this.
-
Some packages will suggest you create a directory and place
the package in that directory. This may be done by downloading and
unzipping a file. It may be done by using Subversion and
sychronizing your subversion copy with the copy on a server. Either
way, you will likely only need to create an operating system link to
this directory and place that link in
site-packages directory.
-
Some packages will suggest you download (or use subversion) to
create a temporary copy. They will provide you with a script —
typically based on setup.py — which moves files
into the correct locations. This is called the
distutils distribution. This will generally
copy the module files to the site-packages
directory.
-
Some packages will rely on setuptools.
This is a package from the Python
Enterprise Application Kit that extends
distuils to further automates download and
installation. This tool, also, works by moving the working library
modules to the site-packages directory.
-
Extending the search path. Either set the
PYTHONPATH environment variable, or put
.PTH files in the site-packages
directory.
Windows Environment
In the Windows environment, the Python_Path
symbol in the Windows registry is used to locate modules.
