Every so often you'll need to configure a Python installation. It's a good idea to know where things are and how to point to them if you have to. In this excerpt from Learning Python by Mark Lutz you'll learn the difference between PATH and PYTHONPATH as well as pick up some useful command-line options to help you get yourself sorted.
After you’ve installed Python, you may want to configure some system settings that impact the way Python runs your code. (If you are just getting started with the language, you can probably skip this section completely; there is usually no need to specify any system settings for basic programs.)
Generally speaking, parts of the Python interpreter’s behavior can be configured with environment variable settings and command-line options. In this section, we’ll take a brief look at both, but be sure to see other documentation sources for more details on the topics we introduce here.
Environment variables—known to some as shell variables, or DOS variables—are system-wide settings that live outside Python and thus can be used to customize the interpreter’s behavior each time it is run on a given computer. Python recognizes a handful of environment variable settings, but only a few are used often enough to warrant explanation here. Table A.1 summarizes the main Python-related environment variable settings.
Table A.1. Important environment variables
System shell search path (for finding “python”)
Python module search path (for imports)
Path to Python interactive startup file
These variables are straightforward to use, but here are a few pointers:
PATHsetting lists a set of directories that the operating system searches for executable programs. It should normally include the directory where your Python interpreter lives (the python program on Unix, or the
python.exefile on Windows).
You don’t need to set this variable at all if you are willing to work in the directory where Python resides, or type the full path to Python in command lines. On Windows, for instance, the
PATHis irrelevant if you run a
cd C:\Python30before running any code (to change to the directory where Python lives), or always type
C:\Python30\pythoninstead of just
python(giving a full path). Also, note that
PATHsettings are mostly for launching programs from command lines; they are usually irrelevant when launching via icon clicks and IDEs.
PYTHONPATHsetting serves a role similar to
PATH: the Python interpreter consults the
PYTHONPATHvariable to locate module files when you import them in a program. If used, this variable is set to a platform-dependent list of directory names, separated by colons on Unix and semicolons on Windows. This list normally includes just your own source code directories. Its content is merged into the
sys.pathmodule import search path, along with the script’s directory, any path file settings, and standard library directories.
You don’t need to set this variable unless you will be performing cross-directory imports—because Python always searches the home directory of the program’s top-level file automatically, this setting is required only if a module needs to import another module that lives in a different directory. See also the discussion of
.pthpath files later in this appendix for an alternative to
PYTHONPATH. For more on the module search path, refer to Chapter 21, Modules: The Big Picture.
PYTHonstartUPis set to the pathname of a file of Python code, Python executes the file’s code automatically whenever you start the interactive interpreter, as though you had typed it at the interactive command line. This is a rarely used but handy way to make sure you always load certain utilities when working interactively; it saves an import.
If you wish to use the
tkinterGUI toolkit (named
Tkinterin 2.6), you might have to set the two GUI variables in the last line of Table A.1 to the names of the source library directories of the Tcl and Tk systems (much like
PYTHONPATH). However, these settings are not required on Windows systems (where
tkintersupport is installed alongside Python), and they’re usually not required elsewhere if Tcl and Tk reside in standard directories.
Note that because these environment settings are external to Python itself, when you set them is usually irrelevant: this can be done before or after Python is installed, as long as they are set the way you require before Python is actually run.
The way to set Python-related environment variables, and what to set them to, depends on the type of computer you’re working on. And again, remember that you won’t necessarily have to set these at all right away; especially if you’re working in IDLE (described in Chapter 3, How You Run Programs), configuration is not required up front.
But suppose, for illustration, that you have generally useful
module files in directories called
package1 somewhere on your machine, and
you want to be able to import these modules from files located in
other directories. That is, to load a file called
spam.py from the
utilities directory, you want to be able
from another file located anywhere on your computer. To make
this work, you’ll have to configure your module search path one way
or another to include the directory containing
spam.py. Here are a few tips on this
On Unix systems, the way to set environment variables
depends on the shell you use. Under the csh
shell, you might add a line like the following in your
.login file to set the Python module
setenv PYTHONPATH /usr/home/pycode/utilities:/usr/lib/pycode/package1
This tells Python to look for imported modules in two
user-defined directories. Alternatively, if you’re using the
ksh shell, the setting might instead appear
.kshrc file and look
Other shells may use different (but analogous) syntax.
If you are using MS-DOS, or some older flavors of
Windows, you may need to add an environment variable configuration
command to your
C:\autoexec.bat file, and reboot your
machine for the changes to take effect. The configuration command
on such machines has a syntax unique to DOS:
You can type such a command in a DOS console window, too,
but the setting will then be active only for that one console
window. Changing your
file makes the change permanent and global to all programs.
On more recent versions of Windows, including XP and
Vista, you can instead set
PYTHONPATH and other variables via the
system environment variable GUI without having to edit files or
reboot. On XP, select the Control Panel, choose the System icon,
pick the Advanced tab, and click the Environment Variables button
to edit or add new variables (
PYTHONPATH is usually a user variable).
Use the same variable name and values syntax shown in the DOS
set command earlier. The
procedure is similar on Vista, but you may have to verify
operations along the way.
You do not need to reboot your machine, but be sure to restart Python if it’s open so that it picks up your changes—it configures its path at startup time only. If you’re working in a Windows Command Prompt window, you’ll probably need to restart that to pick up your changes as well.
If you are an experienced Windows user, you may also be
able to configure the module search path by using the Windows
Registry Editor. Go to Start→Run... and type
regedit. Assuming the typical registry
tool is on your machine, you can then navigate to Python’s entries
and make your changes. This is a delicate and error-prone
procedure, though, so unless you’re familiar with the registry, I
suggest using other options (indeed, this is akin to performing
brain surgery on your computer, so be careful!).
Finally, if you choose to extend the module search path with
.pth file instead of the
PYTHONPATH variable, you might instead
code a text file that looks like the following on Windows (e.g.,
Its contents will differ per platform, and its container directory may differ per both platform and Python release. Python locates this file automatically when it starts up.
Directory names in path files may be absolute, or relative
to the directory containing the path file; multiple
.pth files can be used (all their
directories are added), and
.pth files may appear in various
automatically checked directories that are platform- and
version-specific. In general, a Python release numbered Python
N.M typically looks for path files in
Windows, and in
/usr/local/lib/site-python on Unix and
Linux. See Chapter 21, Modules: The Big Picture for more on using path
files to configure the
import search path.
Because environment settings are often optional, and because this isn’t a book on operating system shells, I’ll defer to other sources for further details. Consult your system shell’s manpages or other documentation for more information, and if you have trouble figuring out what your settings should be, ask your system administrator or another local expert for help.
When you start Python from a system command line (a.k.a. a shell prompt), you can pass in a variety of option flags to control how Python runs. Unlike system-wide environment variables, command-line options can be different each time you run a script. The complete form of a Python command-line invocation in 3.0 looks like this (2.6 is roughly the same, with a few option differences):
python [-bBdEhiOsSuvVWx?] [-c
script| - ] [
Most command lines only make use of the
args parts of this format, to run a
program’s source file with arguments to be used by the program
itself. To illustrate, consider the following script file,
main,py, which prints the command-line
arguments list made available to the script as
# File main.py import sys print(sys.argv)
In the following command line, both
main.py can also be complete directory
paths, and the three arguments (
–c) meant for the script show up in the
sys.argv list. The first item in
sys.argv is always the script file’s name,
when it is known:
python main.py a b –c# Most common: run a script file ['main.py', 'a', 'b', '-c']
Other code format specification options allow you to specify
Python code to be run on the command line itself (
-c), to accept code to run from the
standard input stream (a
read from a pipe or redirected input stream file), and so on:
python -c "print(2 ** 100)"# Read code from command argument 1267650600228229401496703205376 c:\Python30>
python -c "import main"# Import a file to run its code ['-c'] c:\Python30>
python - < main.py a b –c# Read code from standard input ['-', 'a', 'b', '-c'] c:\Python30>
python - a b -c < main.py# Same effect as prior line ['-', 'a', 'b', '-c']
–m code specification
locates a module on Python’s module search path (
sys.path) and runs it as a top-level
script (as module
Leave off the “.py” suffix here, since the filename is a
python -m main a b –c# Locate/run module as script ['c:\\Python30\\main.py', 'a', 'b', '-c']
–m option also supports
running modules in packages with relative import syntax, as well as
modules located in
archives. This switch is commonly used to run the
pdb debugger and
profile profiler modules from a command
line for a script invocation rather than interactively, though this
usage mode seems to have changed somewhat in 3.0 (
profile appears to have been affected by
the removal of
execfile in 3.0,
pdb steps into superfluous
input/output code in the new 3.0
python -m pdb main.py a b -c# Debug a script --Return-- > c:\python30\lib\io.py(762)closed()->False -> return self.raw.closed (Pdb) c c:\Python30>
C:\python26\python -m pdb main.py a b -c# Better in 2.6? > c:\python30\main.py(1)
() -> import sys (Pdb) c c:\Python30>
python -m profile main.py a b -c# Profile a script c:\Python30>
python -m cProfile main.py a b -c# Low-overhead profiler
Immediately after the “python” and before the designation of
code to be run, Python accepts additional arguments that control its
own behavior. These arguments are consumed by Python itself and are
not meant for the script being run. For example,
-O runs Python in optimized mode,
-u forces standard streams to be
interactive mode after running a script:
python –u main.py a b -c# Unbuffered output streams
Python 2.6 supports additional options that promote 3.0
-Q) and detecting inconsistent tab
indentation usage, which is always detected and reported in 3.0
-t; see Chapter 12, if Tests and Syntax Rules). See the Python manuals or
reference texts for more details on available command-line options.
Or better yet, ask Python itself—run a command-line form like
to request Python’s help display, which documents available
command-line options. If you deal with complex command lines, be
sure to also check out the standard library modules
optparse, which support more sophisticated
Learn more about this topic from Learning Python, 4th Edition.
Google and YouTube use Python because it's highly adaptable, easy to maintain, and allows for rapid development. If you want to write high-quality, efficient code that's easily integrated with other languages and tools, this hands-on book will help you be productive with Python 3.0 quickly. Each chapter includes a unique Test Your Knowledge section with practical exercises and quizzes, so you can practice new skills and test your understanding as you go.