This PEP proposes a new a per user site-packages directory to allowusers the local installation of Python packages in their home directory.
Current Python versions don’t have a unified way to install packagesinto the home directory of a user (except for Mac Frameworkbuilds). Users are either forced to ask the system administrator toinstall or update a package for them or to use one of the manyworkarounds like Virtual Python[1], Working Env[2] orVirtual Env[3].
It’s not the goal of the PEP to replace the tools or to implementisolated installations of Python. It only implements the most commonuse case of an additional site-packages directory for each user.
The feature can’t be implemented using the environment variablePYTHONPATH. The env var just inserts a new directory to the beginningofsys.path but it doesn’t parse the pth files in the directory. Afull blown site-packages path is required for several applicationsand Python eggs.
site directory (site-packages)
A directory insys.path. In contrast to ordinary directories the pthfiles in the directory are processed, too.
user site directory
A site directory inside the users’ home directory. A user sitedirectory is specific to a Python version. The path containsthe version number (major and minor only).
- Unix (including Mac OS X)
~/.local/lib/python2.6/site-packages- Windows
%APPDATA%/Python/Python26/site-packages
user data directory
Usually the parent directory of the user site directory. It’s meantfor Python version specific data like config files, docs, imagesand translations.
- Unix (including Mac)
~/.local/lib/python2.6- Windows
%APPDATA%/Python/Python26
user base directory
It’s located inside the user’s home directory. The user site anduse config directory are inside the base directory. On some systemsthe directory may be shared with 3rd party apps.
- Unix (including Mac)
~/.local- Windows
%APPDATA%/Python
user script directory
A directory for binaries and scripts.[10] It’s shared across Pythonversions and the destination directory for scripts.
- Unix (including Mac)
~/.local/bin- Windows
%APPDATA%/Python/Scripts
On Windows theApplication Data directory (akaAPPDATA) was chosenbecause it is the most designated place for application data. Microsoftrecommends that software doesn’t write toUSERPROFILE[5] andMyDocuments is not suited for application data, either.[8] The codedoesn’t query the Win32 API, instead it uses the environment variable%APPDATA%.
The application data directory is part of the roaming profile. In networkswith domain logins the application data may be copied from and to the acentral server. This can slow down log-in and log-off. Users can keepthe data on the server by e.g. setting PYTHONUSERBASE to the value“%HOMEDRIVE%%HOMEPATH%Applicata Data”. Users should consult their localadministrator for more information.[13]
On Unix~/.local was chosen in favor over~/.python because thedirectory is already used by several other programs in analogy to/usr/local.[7][11]
On Mac OS X Python uses ~/.local directory as well.[12] Framework buildsof Python include~/Library/Python/2.6/site-packages as an additionalsearch path.
The site module gets a new methodadduserpackage() which adds theappropriate directory to the search path. The directory is not added ifit doesn’t exist when Python is started. However the location of theuser site directory and user base directory is stored in an internalvariable for distutils.
The user site directory is added before the system site directoriesbut after Python’s search paths andPYTHONPATH. This setup allowsthe user to install a different version of a package than the systemadministrator but it prevents the user from accidentally overwriting astdlib module. Stdlib modules can still be overwritten withPYTHONPATH.
For security reasons the user site directory isnot added tosys.path when the effective user id or group id is not equal to theprocess uid / gid[9]. It’s an additional barrier against code injectioninto suid apps. However Python suid scriptsmust always use the -Eand -s option or users can sneak in their own code.
The user site directory can be suppressed with a new option-s orthe environment variablePYTHONNOUSERSITE. The feature can bedisabled globally by settingsite.ENABLE_USER_SITE to the valueFalse. It must be set by editingsite.py. It can’t be alteredinsitecustomize.py or later.
The path to the user base directory can be overwritten with theenvironment variablePYTHONUSERBASE. The default location is usedwhenPYTHONUSERBASE 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 requireddirectories 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 basedirectory to the search paths for header files and libraries. It alsoadds the lib/ directory to rpath.
Thesite module gets two arguments--user-base and--user-siteto print the path to the user base or user site directory to the standardoutput. The feature is intended for scripting, e.g../configure--prefix$(python2.5-msite--user-base)
distutils.sysconfig will get methods to access the private variablesof site. (not yet implemented)
The Windows updater needs to be updated, too. It should create a menuitem which opens the user site directory in a new explorer windows.
TBD
A reference implementation is available in the bug tracker.[4]
This document has been placed in the public domain.
[6] Initial suggestion for a per user site-packages directoryhttps://mail.python.org/archives/list/python-dev@python.org/message/V23CUKRH3VCHFLV33ADMHJSM53STPA7I/
Source:https://github.com/python/peps/blob/main/peps/pep-0370.rst
Last modified:2025-02-01 08:55:40 GMT