Note: This page has not been updated, and is not needed by users who are using the Enthought distribution described under Quick Start or Python . That should be just about everybody, but I have retained this page in case Enthought stops making their distribution available without charge, and also for users who might want some additional information about what parts of a Python installation are actually used by the courseware.
What do you need to install?
To run the courseware, you need to install python and the array-handline package numpy. This page deals only with the basic Python installation. Installation and use of the courseware modules is described under Courseware. In order to display graphics within Python, you will also need to install a graphics package, as described under Graphics. For basic information on starting up the python interpreter and writing and running scripts, see Learning Python. You can write scripts using any text editor you like, and run them using the basic command-line interpreter, but almost all installations of Python come with a very nice integrated development environment called idle, which offers a smarter interpreter window and also an easy-to-use editor that's aware of Python syntax. idle needs to be run in a windowing environment that displays graphics. You do not need to install a graphics package to run idle, since any modern computer will have a suitable windowing system. On Linux systems, idle uses the x11 windowing system, which is also the native windowing system for Linux. This is useful, because it allows idle to be run on a server but put up a window on your own computer over the network. Mac OS X comes shipped with both x11 and its native windowing system; the current versions of Python for the Mac use the native windowing system to run idle, and Windows implementations also use the native Windows windowing environment. If you are using Python by logging into a server, you will need x11 on your own machine in order to use idle, or indeed to see any graphics on your own screen.
Do you already have Python?
This section is only for Mac and Linux users who want a quick-start without needing to do a Python installation of their own. It is highly recommended to do a fresh installation, so most users should just skip to the next section.
All Mac OSX operating systems since 10.4 come shipped with a version of Python installed, and the versions since 10.5 are very complete, generally including both numpy and idle. Most Linux systems also come with a complete and usable Python installation. On a Mac, and to a lesser extent on Linux, it is recommended that you do a separate Python installation of your own, so you have better control of which version you are using and so you don't have to mess with stuff in the operating system directories. On Mac OS10.6 and higher you also have to keep in mind that the pre-installed version is 64-bit, and so will only work with compiled add-on modules that are also 64-bit (most of the courseware modules and chapter scripts will work fine, though, since only a few of these require compiled add-ons). Nonetheless, to get started learning the language, and for doing basic computations, the pre-installed versions are fine. As far as I am aware, Windows never comes shipped with Python, so the following instructions in this topic apply only to Mac and Linux. If you have a pre-installed version, that's enough to get you started with the language, but chances are you'll soon want to scroll down to the Installing Python heading below, and learn how to install a customized version.
To find whether you have Python, and which version, open a terminal window (that's any window on Linux, and the window you get with either the Terminal utility or x11 on Mac) and type
followed by a return, at the prompt. This will bring you into the python interpreter, and you will get a python prompt. If the computer complains that the command wasn't found, then python isn't installed. (or, it is installed, but the location isn't in your default search path for finding commands). If you get the prompt, it will also tell you what version of Python you have, and what version of the compiler it was built with (which matters for a few compiled add-on modules). Assuming that you have gotten the Python prompt, to find if you have numpy, just type
If everything is OK, you'll just get the Python prompt back with no message. If numpy isn't installed Python will tell you it can't find the module. Now you can quit Python by typing control-D, and check to see if you have idle installed. To do that, go to a terminal window and type
If you are on a Mac with a relatively recent operating system or installation of Python, this will work regardless of whether you are using a plain terminal window or an x11 terminal window (an xterm), since once it starts up idle, the native Mac windowing system is used. (On older installations idle uses x11 for windowing, and you need to start idle from an xterm, but Python never came pre-installed with idle on the older systems anyway). If you are starting idle on a remote server to which you are logged on through a terminal window, then you must be logged on via an xterm (use ssh -Y to log in, or ssh -X on older systems), otherwise idle can't put up its window. Either way, if everything is OK, you should get an idle Python shell window, with an idle menu bar either in the window or at the top of your screen, depending on the system.
Which version of Python?
You should stay with a 2.X version, since Python 3.X is not backward compatible (mostly because of some stupid changes they made to the print statement). The current production version of Python is 2.7, and it is now working fine with the courseware, though 2.6 should also work.
You also need to decide whether to do a 32-bit or 64-bit installation of Python (look here for an explanation). 64 bit installations are available for Python 2.7 and later, with some availability for Python 2.6 as well. I am generally recommending staying with 32-bits if possible, but 64 bit versions of the necessary libraries are gradually becoming widely available, so soon 64 bits will become the installation of choice. For now, the main problem with going to 64 bit involves the use of the Climt_lite interface to the ccm radiation model, which so far we have only compiled for 32 bits on the Mac; on Linux you can easily build it for your own system, and so far we haven't ported it to Windows at all. The PyNgl graphics package is now available in both 32 bit and 64 bit versions.
By far the easiest way to install the basic Python software you need to run the courseware is to use the Enthought distribution, which is available in 32 and 64 bit versions for Mac, Linux and Windows and installs easily using a one-click installer. This distribution gives you Python and numpy, and also gives you the excellent MatPlotLib graphics package. With MatPlotLib, you don't even really need to install PyNGL. Currently, my ClimateGraphics.py module can only use PyNGL as a graphics driver, but MatPlotLib is so easy to use you can easily write your own graphing commands, while waiting for my next release of ClimateGraphics.py, which will support MatPlotLib. Using MatPlotLib with the Enthought distribution is by far the simplest way to go if you want to use graphics on a Windows machine, since then you won't have to install CygWin to get the the x11 windowing system (used by PyNgl). There have been some problems reported in installing PyNgl on Debian Linux systems, and the Enthought distribution with MatPlotLib may be the solution of choice in that case as well. Note that the Enthought distribution is FREE for academic users.
If you want to use PyNGL with the Enthought distribution, you can install it on top of Enthought in precisely the same way you would if installing it on top of the Sourceforge Python distribution described below.
Python for all systems can be downloaded from python.org here . Version 2.6 of Python can be downloaded here. The precompiled binaries for 2.6 on Mac OSX are all 32-bit versions. If you want to make the leap to a 64 bit world, you should look for a precompiled 2.7 or higher version that is explicitly flagged as 64 bit for your operating system (OS 10.6 or higher on the Mac). By the way, the version of Python that ships with Mac OSX is a 64 bit version, and will work only with add-on software built for 64 bit. The Mac OS 10.6 Python already ships with a compatible
numpy, so the compatibility only affects your installation of Climt_lite and PyNGL. However, I do recommend installing a fresh version of Python (as described below), since that gives you more flexibility in upgrading things and picking versions, without having to mess with your operating system directories (always a hazard to do). The Python installation also installs the idle integrated development editor.
The download page comes up showing only the latest release of Python, which is presently Python 2.7. If you want it, you can find Python 2.6.6 here; the later release of Python 2.6 does not include binary installers, and in fact the 2.6.6 release is no longer linked even on the "earlier releases" link, but the link given above still seems to work. Look for a single-click binary installer; most users will not want to build Python from source code.
- Installing on Mac OSX: The distribution is in the form of a Mac Installer disk image (.dmg) file. After you download it from the directory for the release you want, just click on the disk image to mount it, then click on the installer to install it, and follow the directions. The installer installs Python in the /Library/Frameworks/Python.framework directory, which becomes the root directory for anything else you add on to Python. It does not affect the version of Python that ships with the system. The installer also puts a link to the python command in the directory /usr/local/bin , so that when you type the command python or idle in a terminal window, it executes the most recent version of Python that you installed. (Note that for the Mac distribution, idle uses the native Mac windowing system rather than x11). To check which version of Python you are using, type the command which python or which idle into a command window. The first command should return /usr/local/bin/python , for example, and if you then issue the command ls -l /usr/local/bin/python you will see the original file it points to. Some versions of the installer may point directy to /Library/Frameworks/Python.framework/Versions/Current/bin/python. The installer also puts a Python2.X folder in your Applications folder, which contains an icon that you can double-click to start idle (which also gives you a Python interpreter window). Advanced users can alternately download the source code tarball (which is system independent) and build Python from source, but there is little point in doing so unless you have a special configuration not covered by any of the precompiled releases.
- Installing on Linux: Download the sourcecode tarball and build from source. It may also be possible to install Python and idle directly from the command line using Debian tools, without going through Sourceforge.
- Installing on Windows:Clickable installers are provided for both 32 and 64 bit Windows versions. Just download and execute, then follow instructions. General tips on installing and using Python on Windows are found here. Note that (as far as I can tell), the 32 bit version will refuse to install if you are using a 64 bit version of Windows, so you will have to install the 64 bit version in that case.
Which python am I using?
There could be several different versions of Python on the system you are using. When starting up Python by clicking on an icon, this isn't an issue, since each version would have its own icon. However, when starting Python from a command line, e.g. by typing
python, you need to make sure things have been set up so that the system finds the version of Python you wanted. You can always invoke a specific version of Python by giving the full path name to the executable, but most operating systems set things up so that a command is looked for in a specific set of directories in a specific order; on Linux and Mac OS X, this is usually done by setting the PATH environment variable, and normally the installer will take care of the job of setting up the path so that the newly installed version is the default one. You can check what executable is actually invoked by any given command on Linux or Mac OS X by using the
which command. For example, on my current system I get:
$ which python
and similarly for
canopy or any other command . If you are not getting the version of Python you want, you will need to edit your shell configuration file to set the search path properly. You can read about shells and environment variables here.
numpy for all systems is available from the Sourceforge Numpy Site . For most systems, precompiled binaries are available. On the Sourceforge page, you'll see various folders. Open (or expand) the Numpy folder (listed under the heading "All Files"), and then the folder for the version that you want. Distributions for all operating systems are given in the same folder. Make sure to pick a 32 or 64 bit version that corresponds to whether you are running a 32 bit or 64 bit Python installation. (Most people these days will be running 64 bit).
The package f2py is distributed as part of numpy. f2py is a powerful tool for advanced users, since it allows one to very simply turn compiled Fortran (and some kinds of c) code into a new Python command. You need to have installed a compatible Fortran compiler (e.g. gfortran ). f2py is used to build the courseware module CliMT , which provides an interface to the ccm radiation code. Documentation on use of f2py can be found here.
- Installing on Mac OSX: The distribution is in the form of a disk image (.dmg) file. After you download it, just click on the disk image to mount it, then click on the installer to install it, and follow the directions. You need to have first installed a compatible version of Python. (The installer will tell you if you haven't done this). For 32 bit Python 2.6, the file you want is numpy-1.3.0-py2.6-macosx10.5.dmg for numpy1.3, or numpy-1.4.1-py2.6-python.org.dmg for numpy1.4.1. I have not yet tried the latter version, so I recommend using numpy1.3 for now. If you have decided to make the leap to a 64 bit world, and have installed a 64 bit OS10.6 version of Python, then you may have to build a compatible version of numpy from one of the source distributions given on the Sourceforge site, until a precompiled binary becomes available. If you have installed Python 2.7, you should look for a compatible version of numpy. Earlier versions should also work with Python 2.7, but the installer may have some trouble figuring out where to put it.
- Installing on Linux: For Linux the recommended practice when using the Sourceforge distribution is to build numpy from source files. These are available in the directories for individual versions with names like numpy-1.4.1.tar.gz . Various Linux distributions, especially Debian, offer command-line tools to simplify installation of add-on software, and there is a good chance that numpy is available through this channel as well.
- Installing on Windows: Executable installers are available with file names like numpy-1.4.1-win32-superpack-python2.6.exe . The "superpack" designation means that numpy is installed along with various other goodies useful for scientific work. See the release notes for details. At the time of writing, Sourceforge does not offer a 64 bit binary, so if you are working with 64 bit Python for one reason or another, by far your best alternative is to use the Enthought distribution (which is probably your best alternative anyway, regardless of what system you are using.
Normally, an installer will automatically find the right place in your Python installation to put any add-ons you want to be able to use using the
import command in Python. There are various ways to specify additional places where Python should look for modules to import (e.g. setting the PYTHONPATH environment variables), but the normal place to install extensions that are meant to be permanently and universally available (like
numpy or graphics packages) is a directory called
site-packages . Normally you will not need to know where this directory is, since the installer of the extension software will find it and put things there automatically. However, there are some packages that don't have nice installation scripts, where you might need to put things into the right directory by hand. This is becoming a less common situation, but I provide some information about the location of
site-packages below for those who develop a need to know.
Each Python installation on your system will have it's own
site-packages directory, and these are located in different places depending on not only what kind of operating system you have, but what kind of Python installer was used to install Python. Some things are always the same, in that for each Python installation,
site-packages is located in a directory path like
where "2.7" is replaced by the actual version number of the Python you are using, but where the directory
lib is located can vary a lot. For example, for many standard Mac OS X installations, this will be a deep down subdirectory of /Library/Frameworks/Python.framework . For example, if you installed Python2.7, the full path of the directory to move the files to is:
Note that the Enthought Canopy distribution uses virtual environments, and the version of
site-packages the user should modify is in the user's own Library directory, not the system-wide Library. For example, on my recent installation of 64-bit Canopy, the directory is in my own home directory at:
which has the advantage that I can modify it without needing administrator privileges. Linux installations can install Python in a variety of different places, and there are even some cases where some versions of Linux Python may use a different name for the directory.
You may be able to locate the directory by using Spotlight (on a Mac) to search for the phrase site-packages, but be careful, as you may have more than one such folder and also the Spotlight database might not be up to date and might not find them all. On Mac or Linux you can also do a which python and then do an ls -l on the result to find the root directory for your python installation. The part of the directory path before the "bin" directory is where you want to search downward from to find lib/pythonX.Y/site-packages.
If using python2.7 or above, the best way of all to find the
site-packages directory is to use the module
site within the Python interpreter. For example:
Enthought Canopy Python 2.7.6 | 64-bit | (default, Jun 4 2014, 16:42:26)
[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import site
This will return the correct directory for the version of Python the interpreter is running in. The function actually returns a list of all
site-packages directories, but the line as written extracts the first in the list, which is the first place the interpreter looks and is usually the one you want. This is how installers find the
site-packages directory for current versions of Python.