Windows Notes

On Windows the Application Data directory (aka APPDATA ) was chosen because it is the most designated place for application data. Microsoft recommends that software doesn’t write to USERPROFILE [5] and My Documents is not suited for application data, either. [8] The code doesn’t query the Win32 API, instead it uses the environment variable %APPDATA%.

The application data directory is part of the roaming profile. In networks with domain logins the application data may be copied from and to the a central server. This can slow down log-in and log-off. Users can keep the data on the server by e.g. setting PYTHONUSERBASE to the value “%HOMEDRIVE%%HOMEPATH%Applicata Data”. Users should consult their local administrator for more information. [13]

Unix Notes

On Unix ~/.local was chosen in favor over ~/.python because the directory is already used by several other programs in analogy to /usr/local . [7] [11]

Mac OS X Notes

On Mac OS X Python uses ~/.local directory as well. [12] Framework builds of Python include ~/Library/Python/2.6/site-packages as an additional search path.

Implementation

The site module gets a new method adduserpackage() which adds the appropriate directory to the search path. The directory is not added if it doesn’t exist when Python is started. However the location of the user site directory and user base directory is stored in an internal variable for distutils.

The user site directory is added before the system site directories but after Python’s search paths and PYTHONPATH . This setup allows the user to install a different version of a package than the system administrator but it prevents the user from accidentally overwriting a stdlib module. Stdlib modules can still be overwritten with PYTHONPATH .

For security reasons the user site directory is not added to sys.path when the effective user id or group id is not equal to the process uid / gid [9] . It’s an additional barrier against code injection into suid apps. However Python suid scripts must always use the -E and -s option or users can sneak in their own code.

The user site directory can be suppressed with a new option -s or the environment variable PYTHONNOUSERSITE . The feature can be disabled globally by setting site.ENABLE_USER_SITE to the value False . It must be set by editing site.py . It can’t be altered in sitecustomize.py or later.

The path to the user base directory can be overwritten with the environment variable PYTHONUSERBASE . The default location is used when PYTHONUSERBASE is not set or empty.

distutils.command.install (setup.py install) gets a new argument --user to install packages in the user site directory. The required directories are created on demand.

distutils.command.build_ext (setup.py build_ext) gets a new argument --user which adds the include/ and lib/ directories in the user base directory to the search paths for header files and libraries. It also adds the lib/ directory to rpath.

The site module gets two arguments --user-base and --user-site to print the path to the user base or user site directory to the standard output. The feature is intended for scripting, e.g. ./configure --prefix $(python2.5 -m site --user-base)

distutils.sysconfig will get methods to access the private variables of site. (not yet implemented)

The Windows updater needs to be updated, too. It should create a menu item which opens the user site directory in a new explorer windows.

Backwards Compatibility

Reference Implementation

A reference implementation is available in the bug tracker. [4]

This document has been placed in the public domain.

References

[6] Initial suggestion for a per user site-packages directory https://mail.python.org/archives/list/[email protected]/message/V23CUKRH3VCHFLV33ADMHJSM53STPA7I/