In conjunction with our Python user community, Livermore Computing (LC) maintains Python and a set of site-specific packages (modules) on all production TOSS systems. The information herein, which includes the supported versions of Python and site-packages, the description of each site-package, and Python development techniques, will be useful in using Python under LC environments. Where possible, the links to external sites are also provided. General information about the Python programming language is available at the Python Web site. A LC Confluence Space allows users to share tips and tricks and to post requests for site-package additions and an Institutional Confluence Space provides additional information including a supported Python Wheelhouse.
On Linux clusters, LC maintains the default Python command for version 2 as /usr/tce/bin/python and for version 3 as /usr/tce/bin/python3. Unless users modify their standard search paths, /usr/tce/bin/python gets invoked when the python command is typed at a UNIX prompt because /usr/tce/bin takes precedence over any other paths in the standard search path that LC configures. Note that this is not the same as the OS-included /usr/bin/python. The LC-supported Python installations were built with the Spack package manager and ultimately reside in /collab/usr/gapps, however, symlinks are created in /usr/tce/packages/python for convenience. Only a few of the Python bin binaries are made available directly in /usr/tce/bin/ (python, ipython, cython, f2py, idle, and pyMPI), so other commands (pytest, virtualenv, pip, and others) will default to their /usr/bin OS-installed versions. To get all of the LC-supported Python installation's binaries in your $PATH, users are advised to load the python module by running module load python. Instructions on loading the python module can be found below and more general information about modules at LC can be found on the LC confluence wiki here.
In addition to the default version, LC maintains an older version of Python—typically the previous default—to ensure a smooth transition between upgrades. This old version is available in /usr/tce/bin/python-<old_version>. For example, when version 2.7.13 replaced version 2.7.11 as the default version, the latter became accessible via the python-2.7.11 command. LC supports the old version until the transition is believed to be complete. Newer versions may be similarly available. Users can load the python module to modify their default.
For each Python version, LC supports a set of modules, also known as site-packages, generally beneficial to our user community. Our package selection process begins when a package is requested by a user. LC first studies if it can generally benefit the Python users on the LC machines before committing to install and maintain it. If it turns out to be too specific to the individual requester, we recommend that this user make a side-installation and add the installation path to their Python search path via the PYTHONPATH environment variable or that the user use virtualenv to manage their own Python environment. Site package requests can also be made and tracked on the site-package request wiki. The complete list of the site-packages that LC maintains is available through the following links:
Note: Our operating system installation includes a build of Python in /usr/bin/python, which is typically a slightly older version of Python. You may use this version if it works for you; however, be aware that updates, patches, and site-package additions to this Python build are usually scheduled along with the OS upgrades. We therefore encourage you to use /usr/tce/bin/python because we can more flexibly modify that installation to your needs.
We have installed virtualenv to enable users to manage their own Python build while leveraging the LC-supported Python installation. Virtualenv copies portions of a base Python installation into a user-specified directory while still pointing to the base Python installation. The virtualenv copy thus has access to the base Python installation's site-packages (and will track updates) while also allowing the user to install additional or updated site packages.
To create a virtualenv environment, run:
/usr/tce/packages/python/default/bin/virtualenv --system-site-packages <yourprefix>
Note that you need to supply the --system-site-packages argument to pick up the default site-packages. This command creates a virtualenv environment in the specified <yourprefix> directory. You can then access this Python via <yourprefix>/bin/python or by running <yourprefix>/bin/activate to set your $PATH such that you can just run python. There are many options and customizations possible with virtualenv. More information about vitrualenv is available on the virtualenv Web page.
If you are using virtualenv, you can install site packages directly into your virtualenv Python environment. One method is to use pip, which is included in the /bin directory of your virtualenv environment. There are several ways to use pip, as mentioned in the pip documentation. One method is to download the source tarball for the desired package and then run:
% <yourprefix>/bin/pip install <packagename-version>.tar.gz
You can also manually install packages using distutils by running the following command from the package source directory with your virtualenv python:
% <yourprefix>/bin/python setup.py install
With virtualenv and the above examples, the site package can be imported directly, without having to set PYTHONPATH, when you run <yourprefix>/bin/python.
If you do not use virtualenv, you can still install your own site packages, but they cannot be built-in to the actual Python installation. Instead, you will have to run distutils with the --prefix option, for example:
% /usr/tce/packages/python/default/bin/python setup.py install --prefix=<siteprefix>
Note that the path used to install the package should be /usr/tce/packages/python/default/bin/python not /usr/tce/bin/python. The /usr/tce/bin/python path is a script and due to the symlink structure and how distutils works, the build may not work properly if you build the package with the /usr/tce/bin/python path. We also suggest including a $SYS_TYPE directory in the specified siteprefix (i.e., --prefix=$HOME/local/$SYS_TYPE), to separate installations for various OS versions and architectures. In order to load the site package, you will need to add the installation directory, which is typically <siteprefix>/lib/python<version>/lib/site-packages, to your PYTHONPATH environment variable. Because home file systems are mounted across multiple platforms, we generally advise against installing with the --user option, which installs packages in $HOME/.local. This may cause conflicts when trying to run Python codes across multiple OS versions or across various architectures.
Additional information about installing Python modules is available on the Installing Python Modules page.
For MPI parallelism in Python, users are advised to use the mpi4py package.
LC also maintains and supports pyMPI, an MPI extension to the Python programming language. However, users are advised to use mpi4py which is actively being developed, while PyMPI has not been maintained for some time now. PyMPI is supported on all LC OCF and SCF CHAOS systems. A version is available at /usr/tce/bin/pyMPI that always depends on the default Python. For more information about pyMPI, please read pyMPI. The default pyMPI is currently pyMPI 2.5b6.
Builds of Python 3.5.2 and 3.6.0 are available with a reduced set of site packages. The site packages provided are the subset of packages that LC supports with the 2.X installations that have been ported to Python 3. As additional packages are ported, they will be installed in the Python 3 builds. Note that the executable for Python 3 is python3 as opposed to python. Loading a Python 3.X module will only affect the version of the python3 command and not the python command.
Below are a few basic, useful techniques for running Python. Users are also encouraged to share pointers on the Python tips and tricks wiki.
You can use Lmod Modules to control which version of Python to use. For more information, see the TOSS 3 Lmod wiki.
To see which versions of Python are available:
% module avail python -------------------------- /usr/tce/modulefiles/Core --------------------------- python/2.7.11 python/2.7.13 (D) python/3.5.1 python/3.6.0 Where: D: Default Module
To use the default version of Python:
% python Python 2.7.13 (default, Jan 3 2017, 11:21:42) [GCC 4.8.5 20150623 (Red Hat 4.8.5-11)] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>>
To use a specific version of Python:
% module load python/2.7.11 % python Python 2.7.11 (default, Jun 10 2016, 11:20:30) [GCC 4.8.5 20150623 (Red Hat 4.8.5-4)] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>>
Invoking Python in a Script
Place the following line at the beginning of your Python script:
#! /bin/env python
Change the permissions of your script to add execute privileges:
% chmod +x myscript.py
Run your script like an executable:
Note: While you can also use #! /usr/tce/bin/python, we do not recommend doing so because it will cause problems if you are using modules to manage which Python version you are running. Also, be aware that /bin/env python will pick up any alias to Python that you may have set. However, if your script depends on a specific Python version, you should use the full path.
A lot of documentation for Python is available on the Web and in published hardcopy. The Python Web site contains links that are extremely useful. Documents and information specific to LLNL or not easily found at the Python Web site are:
- Python Site Packages (LLNL)
- Debugging Python: Python script debugging using pdb.
- pyDoc: Documentation generator and online help system.
- pyMPI: An introduction to parallel Python using MPI.
If you know of other documentation that should be listed here, please contact the LC Hotline.
If you are getting SSL certificate errors, such as
requests.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:590), you can set your REQUESTS_CA_BUNDLE environment variable to /etc/pki/tls/cert.pem.