ꦫꦣꦺꦤ꧀ꦄꦤ꧀ꦠꦱꦺꦤ

PATH: usr / share / doc / python-docs-2.7.5 / html / _sources / library

:mod:`site` --- Site-specific configuration hook
================================================

.. module:: site
   :synopsis: Module responsible for site-specific configuration.

**Source code:** :source:`Lib/site.py`

--------------

.. highlightlang:: none

**This module is automatically imported during initialization.** The automatic
import can be suppressed using the interpreter's :option:`-S` option.

.. index:: triple: module; search; path

Importing this module will append site-specific paths to the module search path
and add a few builtins.

.. index::
   pair: site-python; directory
   pair: site-packages; directory

It starts by constructing up to four directories from a head and a tail part.
For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads
are skipped.  For the tail part, it uses the empty string and then
:file:`lib/site-packages` (on Windows) or
:file:`lib/python{X.Y}/site-packages` and then :file:`lib/site-python` (on
Unix and Macintosh).  For each of the distinct head-tail combinations, it sees
if it refers to an existing directory, and if so, adds it to ``sys.path`` and
also inspects the newly added path for configuration files.

A path configuration file is a file whose name has the form :file:`{name}.pth`
and exists in one of the four directories mentioned above; its contents are
additional items (one per line) to be added to ``sys.path``.  Non-existing items
are never added to ``sys.path``, and no check is made that the item refers to a
directory rather than a file.  No item is added to ``sys.path`` more than
once.  Blank lines and lines beginning with ``#`` are skipped.  Lines starting
with ``import`` (followed by space or tab) are executed.

.. versionchanged:: 2.6
   A space or tab is now required after the import keyword.

.. index::
   single: package
   triple: path; configuration; file

For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to
:file:`/usr/local`.  The Python X.Y library is then installed in
:file:`/usr/local/lib/python{X.Y}`.  Suppose this has
a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three
subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path
configuration files, :file:`foo.pth` and :file:`bar.pth`.  Assume
:file:`foo.pth` contains the following::

# foo package configuration

foo
   bar
   bletch

and :file:`bar.pth` contains::

# bar package configuration

bar

Then the following version-specific directories are added to
``sys.path``, in this order::

/usr/local/lib/pythonX.Y/site-packages/bar
   /usr/local/lib/pythonX.Y/site-packages/foo

Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar`
directory precedes the :file:`foo` directory because :file:`bar.pth` comes
alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is
not mentioned in either path configuration file.

.. index:: module: sitecustomize

After these path manipulations, an attempt is made to import a module named
:mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
It is typically created by a system administrator in the site-packages
directory.  If this import fails with an :exc:`ImportError` exception, it is
silently ignored.

.. index:: module: usercustomize

After this, an attempt is made to import a module named :mod:`usercustomize`,
which can perform arbitrary user-specific customizations, if
:data:`ENABLE_USER_SITE` is true.  This file is intended to be created in the
user site-packages directory (see below), which is part of ``sys.path`` unless
disabled by :option:`-s`.  An :exc:`ImportError` will be silently ignored.

Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
empty, and the path manipulations are skipped; however the import of
:mod:`sitecustomize` and :mod:`usercustomize` is still attempted.

.. data:: PREFIXES

A list of prefixes for site-packages directories.

.. versionadded:: 2.6

.. data:: ENABLE_USER_SITE

Flag showing the status of the user site-packages directory.  ``True`` means
   that it is enabled and was added to ``sys.path``.  ``False`` means that it
   was disabled by user request (with :option:`-s` or
   :envvar:`PYTHONNOUSERSITE`).  ``None`` means it was disabled for security
   reasons (mismatch between user or group id and effective id) or by an
   administrator.

.. versionadded:: 2.6

.. data:: USER_SITE

Path to the user site-packages for the running Python.  Can be ``None`` if
   :func:`getusersitepackages` hasn't been called yet.  Default value is
   :file:`~/.local/lib/python{X.Y}/site-packages` for UNIX and non-framework Mac
   OS X builds, :file:`~/Library/Python/{X.Y}/lib/python/site-packages` for Mac
   framework builds, and :file:`{%APPDATA%}\\Python\\Python{XY}\\site-packages`
   on Windows.  This directory is a site directory, which means that
   :file:`.pth` files in it will be processed.

.. versionadded:: 2.6

.. data:: USER_BASE

Path to the base directory for the user site-packages.  Can be ``None`` if
   :func:`getuserbase` hasn't been called yet.  Default value is
   :file:`~/.local` for UNIX and Mac OS X non-framework builds,
   :file:`~/Library/Python/{X.Y}` for Mac framework builds, and
   :file:`{%APPDATA%}\\Python` for Windows.  This value is used by Distutils to
   compute the installation directories for scripts, data files, Python modules,
   etc. for the :ref:`user installation scheme <inst-alt-install-user>`.  See
   also :envvar:`PYTHONUSERBASE`.

.. versionadded:: 2.6

.. function:: addsitedir(sitedir, known_paths=None)

Add a directory to sys.path and process its :file:`.pth` files.  Typically
   used in :mod:`sitecustomize` or :mod:`usercustomize` (see above).

.. function:: getsitepackages()

Return a list containing all global site-packages directories (and possibly
   site-python).

.. versionadded:: 2.7

.. function:: getuserbase()

Return the path of the user base directory, :data:`USER_BASE`.  If it is not
   initialized yet, this function will also set it, respecting
   :envvar:`PYTHONUSERBASE`.

.. versionadded:: 2.7

.. function:: getusersitepackages()

Return the path of the user-specific site-packages directory,
   :data:`USER_SITE`.  If it is not initialized yet, this function will also set
   it, respecting :envvar:`PYTHONNOUSERSITE` and :data:`USER_BASE`.

.. versionadded:: 2.7

The :mod:`site` module also provides a way to get the user directories from the
command line:

.. code-block:: sh

$ python3 -m site --user-site
   /home/user/.local/lib/python3.3/site-packages

.. program:: site

If it is called without arguments, it will print the contents of
:data:`sys.path` on the standard output, followed by the value of
:data:`USER_BASE` and whether the directory exists, then the same thing for
:data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`.

.. cmdoption:: --user-base

Print the path to the user base directory.

.. cmdoption:: --user-site

Print the path to the user site-packages directory.

If both options are given, user base and user site will be printed (always in
this order), separated by :data:`os.pathsep`.

If any option is given, the script will exit with one of these values: ``O`` if
the user site-packages directory is enabled, ``1`` if it was disabled by the
user, ``2`` if it is disabled for security reasons or by an administrator, and a
value greater than 2 if there is an error.

.. seealso::

:pep:`370` -- Per user site-packages directory

[+] ..
[-] fpformat.txt [edit]
[-] string.txt [edit]
[-] aetypes.txt [edit]
[-] textwrap.txt [edit]
[-] codecs.txt [edit]
[-] array.txt [edit]
[-] urllib2.txt [edit]
[-] pickle.txt [edit]
[-] 2to3.txt [edit]
[-] ossaudiodev.txt [edit]
[-] markup.txt [edit]
[-] sha.txt [edit]
[-] stat.txt [edit]
[-] itertools.txt [edit]
[-] numeric.txt [edit]
[-] gzip.txt [edit]
[-] pkgutil.txt [edit]
[-] subprocess.txt [edit]
[-] token.txt [edit]
[-] debug.txt [edit]
[-] dummy_thread.txt [edit]
[-] mimify.txt [edit]
[-] bastion.txt [edit]
[-] popen2.txt [edit]
[-] autogil.txt [edit]
[-] importlib.txt [edit]
[-] io.txt [edit]
[-] msilib.txt [edit]
[-] development.txt [edit]
[-] hotshot.txt [edit]
[-] constants.txt [edit]
[-] curses.ascii.txt [edit]
[-] os.txt [edit]
[-] easydialogs.txt [edit]
[-] mutex.txt [edit]
[-] md5.txt [edit]
[-] stdtypes.txt [edit]
[-] bz2.txt [edit]
[-] imgfile.txt [edit]
[-] aetools.txt [edit]
[-] internet.txt [edit]
[-] xml.dom.pulldom.txt [edit]
[-] cookie.txt [edit]
[-] sunau.txt [edit]
[-] archiving.txt [edit]
[-] modules.txt [edit]
[-] base64.txt [edit]
[-] ttk.txt [edit]
[-] tty.txt [edit]
[-] cookielib.txt [edit]
[-] pydoc.txt [edit]
[-] misc.txt [edit]
[-] fm.txt [edit]
[-] whichdb.txt [edit]
[-] imghdr.txt [edit]
[-] datatypes.txt [edit]
[-] dis.txt [edit]
[-] datetime.txt [edit]
[-] userdict.txt [edit]
[-] py_compile.txt [edit]
[-] imputil.txt [edit]
[-] xml.dom.minidom.txt [edit]
[-] multiprocessing.txt [edit]
[-] functools.txt [edit]
[-] audioop.txt [edit]
[-] language.txt [edit]
[-] miniaeframe.txt [edit]
[-] ssl.txt [edit]
[-] copy_reg.txt [edit]
[-] heapq.txt [edit]
[-] syslog.txt [edit]
[-] fileformats.txt [edit]
[-] simplexmlrpcserver.txt [edit]
[-] numbers.txt [edit]
[-] pipes.txt [edit]
[-] shutil.txt [edit]
[-] zlib.txt [edit]
[-] optparse.txt [edit]
[-] allos.txt [edit]
[-] custominterp.txt [edit]
[-] windows.txt [edit]
[-] dbm.txt [edit]
[-] select.txt [edit]
[-] time.txt [edit]
[-] index.txt [edit]
[-] undoc.txt [edit]
[-] plistlib.txt [edit]
[-] htmllib.txt [edit]
[-] warnings.txt [edit]
[-] functions.txt [edit]
[-] argparse.txt [edit]
[-] distutils.txt [edit]
[-] macpath.txt [edit]
[-] fnmatch.txt [edit]
[-] tabnanny.txt [edit]
[-] calendar.txt [edit]
[-] jpeg.txt [edit]
[-] zipimport.txt [edit]
[-] unix.txt [edit]
[-] chunk.txt [edit]
[-] smtplib.txt [edit]
[-] tokenize.txt [edit]
[-] asynchat.txt [edit]
[-] decimal.txt [edit]
[-] cd.txt [edit]
[-] pickletools.txt [edit]
[-] statvfs.txt [edit]
[-] gettext.txt [edit]
[-] sqlite3.txt [edit]
[-] imageop.txt [edit]
[-] dl.txt [edit]
[-] logging.handlers.txt [edit]
[-] zipfile.txt [edit]
[-] copy.txt [edit]
[-] sched.txt [edit]
[-] nis.txt [edit]
[-] timeit.txt [edit]
[-] weakref.txt [edit]
[-] mailbox.txt [edit]
[-] othergui.txt [edit]
[-] sgmllib.txt [edit]
[-] mimewriter.txt [edit]
[-] email.charset.txt [edit]
[-] mmap.txt [edit]
[-] xmlrpclib.txt [edit]
[-] robotparser.txt [edit]
[-] xml.sax.reader.txt [edit]
[-] hmac.txt [edit]
[-] collections.txt [edit]
[-] mimetools.txt [edit]
[-] aifc.txt [edit]
[-] modulefinder.txt [edit]
[-] socketserver.txt [edit]
[-] grp.txt [edit]
[-] getopt.txt [edit]
[-] __future__.txt [edit]
[-] binascii.txt [edit]
[-] symtable.txt [edit]
[-] crypt.txt [edit]
[-] email.encoders.txt [edit]
[-] imaplib.txt [edit]
[-] spwd.txt [edit]
[-] wsgiref.txt [edit]
[-] errno.txt [edit]
[-] email-examples.txt [edit]
[-] sun.txt [edit]
[-] doctest.txt [edit]
[-] resource.txt [edit]
[-] asyncore.txt [edit]
[-] curses.panel.txt [edit]
[-] imp.txt [edit]
[-] htmlparser.txt [edit]
[-] thread.txt [edit]
[-] posix.txt [edit]
[-] repr.txt [edit]
[-] macostools.txt [edit]
[-] colorsys.txt [edit]
[-] bdb.txt [edit]
[-] stringio.txt [edit]
[-] mm.txt [edit]
[-] cgi.txt [edit]
[-] math.txt [edit]
[-] httplib.txt [edit]
[-] urlparse.txt [edit]
[-] aepack.txt [edit]
[-] colorpicker.txt [edit]
[-] binhex.txt [edit]
[-] tk.txt [edit]
[-] xml.txt [edit]
[-] webbrowser.txt [edit]
[-] contextlib.txt [edit]
[-] types.txt [edit]
[-] shelve.txt [edit]
[-] platform.txt [edit]
[-] readline.txt [edit]
[-] locale.txt [edit]
[-] sets.txt [edit]
[-] macosa.txt [edit]
[-] bisect.txt [edit]
[-] email.parser.txt [edit]
[-] xml.sax.txt [edit]
[-] xml.etree.elementtree.txt [edit]
[-] netrc.txt [edit]
[-] new.txt [edit]
[-] bsddb.txt [edit]
[-] fl.txt [edit]
[-] curses.txt [edit]
[-] hashlib.txt [edit]
[-] tarfile.txt [edit]
[-] ftplib.txt [edit]
[-] telnetlib.txt [edit]
[-] macos.txt [edit]
[-] multifile.txt [edit]
[-] dbhash.txt [edit]
[-] netdata.txt [edit]
[-] fileinput.txt [edit]
[-] python.txt [edit]
[-] mac.txt [edit]
[-] filesys.txt [edit]
[-] scrolledtext.txt [edit]
[-] compiler.txt [edit]
[-] tkinter.txt [edit]
[-] random.txt [edit]
[-] mailcap.txt [edit]
[-] fpectl.txt [edit]
[-] fcntl.txt [edit]
[-] ipc.txt [edit]
[-] formatter.txt [edit]
[-] profile.txt [edit]
[-] xml.dom.txt [edit]
[-] email.iterators.txt [edit]
[-] logging.config.txt [edit]
[-] rlcompleter.txt [edit]
[-] idle.txt [edit]
[-] gdbm.txt [edit]
[-] ast.txt [edit]
[-] someos.txt [edit]
[-] cmd.txt [edit]
[-] re.txt [edit]
[-] docxmlrpcserver.txt [edit]
[-] pdb.txt [edit]
[-] rexec.txt [edit]
[-] commands.txt [edit]
[-] restricted.txt [edit]
[-] crypto.txt [edit]
[-] dumbdbm.txt [edit]
[-] email.txt [edit]
[-] linecache.txt [edit]
[-] os.path.txt [edit]
[-] cgitb.txt [edit]
[-] _winreg.txt [edit]
[-] carbon.txt [edit]
[-] turtle.txt [edit]
[-] xml.sax.handler.txt [edit]
[-] json.txt [edit]
[-] email.generator.txt [edit]
[-] struct.txt [edit]
[-] mhlib.txt [edit]
[-] uuid.txt [edit]
[-] threading.txt [edit]
[-] mimetypes.txt [edit]
[-] traceback.txt [edit]
[-] filecmp.txt [edit]
[-] sndhdr.txt [edit]
[-] logging.txt [edit]
[-] getpass.txt [edit]
[-] dummy_threading.txt [edit]
[-] abc.txt [edit]
[-] shlex.txt [edit]
[-] email.mime.txt [edit]
[-] fractions.txt [edit]
[-] email.header.txt [edit]
[-] marshal.txt [edit]
[-] symbol.txt [edit]
[-] wave.txt [edit]
[-] urllib.txt [edit]
[-] queue.txt [edit]
[-] operator.txt [edit]
[-] compileall.txt [edit]
[-] sysconfig.txt [edit]
[-] quopri.txt [edit]
[-] inspect.txt [edit]
[-] xdrlib.txt [edit]
[-] __builtin__.txt [edit]
[-] ic.txt [edit]
[-] signal.txt [edit]
[-] dircache.txt [edit]
[-] rfc822.txt [edit]
[-] glob.txt [edit]
[-] stringprep.txt [edit]
[-] tix.txt [edit]
[-] i18n.txt [edit]
[-] email.util.txt [edit]
[-] anydbm.txt [edit]
[-] code.txt [edit]
[-] __main__.txt [edit]
[-] difflib.txt [edit]
[-] unicodedata.txt [edit]
[-] sunaudio.txt [edit]
[-] msvcrt.txt [edit]
[-] site.txt [edit]
[-] codeop.txt [edit]
[-] uu.txt [edit]
[-] winsound.txt [edit]
[-] smtpd.txt [edit]
[-] al.txt [edit]
[-] user.txt [edit]
[-] poplib.txt [edit]
[-] nntplib.txt [edit]
[-] keyword.txt [edit]
[-] ctypes.txt [edit]
[-] socket.txt [edit]
[-] simplehttpserver.txt [edit]
[-] sys.txt [edit]
[-] pyexpat.txt [edit]
[-] configparser.txt [edit]
[-] persistence.txt [edit]
[-] trace.txt [edit]
[-] runpy.txt [edit]
[-] csv.txt [edit]
[-] test.txt [edit]
[-] framework.txt [edit]
[-] gc.txt [edit]
[-] cmath.txt [edit]
[-] exceptions.txt [edit]
[-] pyclbr.txt [edit]
[-] sgi.txt [edit]
[-] parser.txt [edit]
[-] future_builtins.txt [edit]
[-] pwd.txt [edit]
[-] strings.txt [edit]
[-] frameworks.txt [edit]
[-] email.message.txt [edit]
[-] cgihttpserver.txt [edit]
[-] intro.txt [edit]
[-] email.errors.txt [edit]
[-] pprint.txt [edit]
[-] pty.txt [edit]
[-] xml.sax.utils.txt [edit]
[-] posixfile.txt [edit]
[-] tempfile.txt [edit]
[-] termios.txt [edit]
[-] gl.txt [edit]
[-] gensuitemodule.txt [edit]
[-] atexit.txt [edit]
[-] basehttpserver.txt [edit]
[-] unittest.txt [edit]