PyNIfTI - Pythonic access to NIfTI and ANALYZE files

### Navigation

- index
- next |
- previous |
- NIfTI Libraries |
- PyNIfTI Home |
- Documentation »

# Installation

It should be fairly easy to get PyNIfTI running on any system. For the most popular platforms and operating systems there are binary packages provided in the respective native packaging format (DEB, RPM or installers). On all other systems PyNIfTI has to be compiled from source – which should also be pretty straightforward.

## Binary packages

### GNU/Linux

PyNIfTI is available in recent versions of the Debian (since lenny) and Ubuntu (since gutsy in universe) distributions. The name of the binary package is `python-nifti` in both cases.

- PyNIfTI versions in Debian
- PyNIfTI versions in Ubuntu

Binary packages for some additional Debian and (K)Ubuntu versions are also available. Please visit Michael Hanke’s APT repository to read about how you have to setup your system to retrieve the PyNIfTI package via your package manager and stay in sync with future releases.

If you are using Debian lenny (or later) or Ubuntu gutsy (or later) or you have configured your system for Michael Hanke’s APT repository all you have to do to install PyNIfTI is this:

    apt-get update
    apt-get install python-nifti

This should pull all necessary dependencies. If it doesn’t, it’s a bug that should be reported.

Additionally, there are binary packages for several RPM-based distributions, provided through the OpenSUSE Build Service. To install one of these packages first download it from the OpenSUSE software website. Please note, that this site does not only offer OpenSUSE packages, but also binaries for other distributions, including: CentOS 5, Fedora 9-10, Mandriva 2007-2008, RedHat Enterprise Linux 5, SUSE Linux Enterprise 10, OpenSUSE 10.2 up to 11.0. Once downloaded, open a console and invoke (the example command refers to PyMVPA 0.3.1):

    rpm -i python-nifti-0.20080710.1-4.1.i386.rpm

The OpenSUSE website also offers 1-click-installations for distributions supporting it.

A more convenient way to install PyNIfTI and automatically receive software updates is to included one of the `RPM-package repositories`_ in the system’s package management configuration. For e.g. OpenSUSE 11.0, simply use Yast to add another repository, using the following URL:

> http://download.opensuse.org/repositories/home:/hankem/openSUSE_11.0/

For other distributions use the respective package managers (e.g. Yum) to setup the repository URL. The repositories include all core dependencies of PyNIfTI, if they are not available from other repositories of the respective distribution. There are two different repository groups, one for Suse and Mandriva-related packages and another one for Fedora, Redhat and CentOS-related packages.

### Windows

A binary installer for a recent Python version is available from the nifticlibs Sourceforge project site.

There are a few Python distributions for Windows. In theory all of them should work equally well. However, I only tested the standard Python distribution from www.python.org (with version 2.5.2).

First you need to download and install Python. Use the Python installer for this job. Yo do not need to install the Python test suite and utility scripts. From now on we will assume that Python was installed in C:\Python25 and that this directory has been added to the PATH environment variable.

In addition you’ll need NumPy. Download a matching NumPy windows installer for your Python version (in this case 2.5) from the SciPy download page and install it.

PyNIfTI does not come with the required zlib library, so you also need to download and install it. A binary installer is available from the GnuWin32 project. Install it in some arbitrary folder (just the binaries nothing else), find the zlib1.dll file in the bin subdirectory and move it in the Windows system32 directory.

Now, you can use the PyNIfTI windows installer to install PyNIfTI on your system. As always: click Next as long as necessary and finally Finish. If done, verify that everything went fine by opening a command promt and start Python by typing python and hit enter. Now you should see the Python prompt. Import the nifti module, which should cause no error messages:

    >>> import nifti
    >>>

### MacOS X

The easiest installation method for OSX is via MacPorts. MacPorts is a package management system for MacOS, which is in some respects very similiar to RPM or APT which are used in most GNU/Linux distributions. However, rather than installing binary packages, it compiles software from source on the target machine.

The MacPort of PyNIfTI is kindly maintained by James Kyle <jameskyle@ucla.edu>.

In the context of PyNIfTI MacPorts is much easier to handle than the previously available installer for Macs. Although the initial overhead to setup MacPorts on a machine is higher than simply installing PyNIfTI using the former installer, MacPorts saves the user a significant amount of time (in the long run). This is due to the fact that this framework will not only take care of updating a PyNIfTI installation automatically whenever a new release is available. It will also provide many of the optional dependencies of PyNIfTI (e.g. NumPy, nifticlibs) in the same environment and therefore abolishes the need to manually check dozens of websites for updates and deal with an unbelievable number of different installation methods.

MacPorts provides a universal binary package installer that is downloadable at http://www.macports.org/install.php

After downloading, simply mount the dmg image and double click MacPorts.pkg.

By default, MacPorts installs to /opt/local. After the installation is completed, you must ensure that your paths are set up correctly in order to access the programs and utilities installed by MacPorts. For exhaustive details on editing shell paths please see:

> http://www.debian.org/doc/manuals/reference/ch-install.en.html#s-bashconf

A typical .bash_profile set up for MacPorts might look like:

    > export PATH=/opt/local/bin:/opt/local/sbin:$PATH
    > export DYLD_LIBRARY_PATH=/opt/local/lib:$DYLD_LIBRARY_PATH

Be sure to source your .bash_profile or close Terminal.app and reopen it for these changes to take effect.

Once MacPorts is installed and your environment is properly configured, PyNIfTI is installed using a single command:

    > $ sudo port install py25-pynifti

If this is your first time using MacPorts Python 2.5 will be automatically installed for you. However, an additional step is needed:

    $ sudo port install python_select
    $ sudo python_select python25

MacPorts has the ability of installing several Python versions at a time, the python_select utility ensures that the default Python (located at /opt/local/bin/python) points to your preferred version.

Upon success, open a terminal window and start Python by typing python and hit return. Now try to import the PyNIfTI module by doing:

    >>> import nifti
    >>>

If no error messages appear, you have succesfully installed PyNIfTI.

## Compile from source

If no binary packages are provided for your platfom, you can build PyNIfTI from source. It needs a few things to build and run properly:

- Python 2.4 or greater

- NumPy

- SWIG 1.3.29 (or later)

- NIfTI C libraries

    Proper developer packages are prefered, but for convenience reasons a minimal copy is included in the PyNIfTI source package.

### Get the sources

Since June 2007 PyNIfTI is part of the niftilibs family. The source code of PyNIfTI releases can be obtained from the corresponding Sourceforge project site. Alternatively, one can also download a tarball of the latest development snapshot (i.e. the current state of the master branch of the PyNIfTI source code repository).

If you want to have access to both, the full PyNIfTI history and the latest development code, you can use the PyNIfTI Git repository on the Alioth server, a service kindly provided by the Debian project. To view the repository, please point your web browser to gitweb:

> http://git.debian.org/?p=pkg-exppsy/pynifti.git

The gitweb browser also allows to download arbitrary development snapshots of PyNIfTI. For a full clone (aka checkout) of the PyNIfTI repository simply do:

    git clone http://git.debian.org/git/pkg-exppsy/pynifti.git

### Compiling: General instructions

Make sure that the compiled nifticlibs and the corresponding headers are available to your compiler. If they are located in a custom directory, you might have to specify `--include-dirs` and `--library-dirs` options to the build command below. In case, you want to build and use the nifticlibs copy that is shipped with PyNIfTI, this is automatically done for you.

Once you have downloaded the sources, extract the tarball and enter the root directory of the extracted sources. If you do not have the nifticlibs installed, run:

    make

in the root of the extracted source tarball. If you have system-wide installed nifticlibs available on your system, instead simply do:

    python setup.py build

That should build the SWIG wrappers. If this has been done successfully, all you need to do is install the modules by invoking:

    sudo python setup.py install

If sudo is not configured (or even installed) you might have to use `su` instead.

Now fire up Python and try importing the module to see if everything is fine. It should look similar to this:

    Python 2.4.4 (#2, Oct 20 2006, 00:23:25)
    [GCC 4.1.2 20061015 (prerelease) (Debian 4.1.1-16.1)] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import nifti
    >>>

### Building on Windows Systems

On Windows the whole situation is a little more tricky, as the system doesn’t come with a compiler by default. Nevertheless, it is easily possible to build PyNIfTI from source. One could use the Microsoft compiler that comes with Visual Studio to do it, but as this is commercial software and not everybody has access to it, I will outline a way that exclusively involves free and open source software.

First one needs to install the Python and NumPy, if not done yet. Please refer to the installation intructions for the Windows binary package below.

Next we need to obtain and install the MinGW compiler collection. Download the Automated MinGW Installer from the MinGW project website. Now, run it and choose to install the current package. You will need the MinGW base tools, gcc and g++ compiler and MinGW Make. For the remaining parts of the section, we will assume that MinGW got installed in C:\MinGW and the directory C:\MinGW\bin has been added to the PATH environment variable, to be able to easily access all MinGW tools. Note, that it is not necessary to install MSYS to build PyNIfTI, but it might handy to have it.

In addition, PyNIfTI needs the developer version of the zlib library, so you also need to download and install it. A binary installer is available from the GnuWin32 project. It is best to install it into the same directory as MinGW (i.e. C:\MinGW in this example), as all paths will be automatically configured properly.

You also need to download SWIG (actually swigwin, the distribution for Windows). SWIG does not have to be installed, just unzip the file you downloaded and add the root directory of the extracted sources to the PATH environment variable (make sure that this directory contains swig.exe, if not, you haven’t downloaded swigwin).

Now, we are ready to build PyNIfTI. The easiest way to do this, is to make use of the Makefile.win that is shipped with PyNIfTI to build a binary installer package (.exe). Make sure, that the settings at the top of Makefile.win (the file is located in the root directory of the source distribution) correspond to your Python installation – if not, first adjust them accordingly before your proceed. When everything is set, do:

    mingw32-make -f Makefile.win installer

Upon success you can find the installer in the dist subdirectory. Install it as described below.

### MacOS X

Since the MacPorts system basically compiles from source there should be no need to perform this step manually. However, if one intends to compile without MacPorts the XCode developer tools, have to be installed first, as the operating system does not come with a compiler by default. If you want to use or even work on the latest development code, you should also install Git. There is a MacOS installer for Git, that make this step very easy.

Otherwise follow the general build instructions.

### MacOS X and MacPython

When you are comiling PyNIfTI on MacOS X and want to use it with MacPython, please make sure that the NIfTI C libraries are compiled as fat binaries (compiled for both ppc and i386). Otherwise PyNIfTI extensions will not compile.

One can achieve this by adding both architectures to the `CFLAGS` definition in the toplevel Makefile of the NIfTI C library source code or in the file 3rd/nifticlibs/Makefile if you are using the nifticlibs copy that is shipped with the PyNIfTI sources. Like this:

    CFLAGS=-Wall -O2 -I. -DHAVE_ZLIB -arch ppc -arch i386

## Troubleshooting

If you get an error when importing the `nifti` module in Python complaining about missing symbols your niftiio library contains references to some unresolved symbols. Try adding `znzlib` and `zlib` to the linker options the PyNIfTI `setup.py`, like this:

    libraries = [ 'niftiio', 'znz', 'z' ],

### Navigation

- index
- next |
- previous |
- NIfTI Libraries |
- PyNIfTI Home |
- Documentation »