NCL > Download

Install NCL/NCAR Graphics from a precompiled binary

This document explains how to install NCL/NCAR Graphics from a precompiled binary. We highly recommend this method over building from source code.

Please read these special notes if you have a system running Linux, Cygwin, or Mac OS.

The precompiled binary that you download will be a gzipped tar file. Let's assume it's called ncl_ncarg-5.1.1.SunOS_5.10.tar.gz and that it resides in your home directory.

To install NCL/NCARG, you need to do the following steps:

  1. Gunzip the file.
  2. Un-tar the file wherever you want the software to reside.
  3. Set the NCARG_ROOT environment variable and your search path to where NCL resides.
  4. Set the DISPLAY environment variable to indicate where to display graphics.
  5. Put a ".hluresfile" file in your home directory.
  6. Special instructions if you have an OPeNDAP-enabled version of NCL.
  7. Test your NCL/NCARG installation.
  8. Problem with libgfortran.so.x? - Special note for Linux/Mac systems
  9. Notes on compiling an NCAR Graphics program

Gunzip the file

First gunzip the file with the UNIX command gunzip:

    % gunzip ~/ncl_ncarg-5.1.1.SunOS_5.10.tar.gz
Un-tar the file wherever you want the software to reside

Decide where you want NCL/NCARG to reside on your system. The tar file contains both executables and library files, so if you un-tar it, it will create a "bin" directory and a "lib" directory in your current working directory.

For example, if you want the software to reside in the parent directory "/usr/local", then do the following: 

    % mkdir /usr/local
    % cd /usr/local
    % tar -xvf ~/ncl_ncarg-5.1.1.SunOS_5.10.tar
Set the NCARG_ROOT environment variable and your search path to where NCL/NCARG resides

In order to use the software, you must set your NCARG_ROOT environment variable to the parent directory where the NCL executables and accompanying files were installed. You also need to make sure that the directory where the NCL/NCARG executables reside are on your search path. It is best to do this from one of your .* files in your home directory. If you are not sure which shell you are running, you can do an "ls -a" in your home directory to see what kind of files you have that start with ".", and then look in these files to see how environment variables are set.

In the example above, we would set these with the following:

From csh: 

    setenv NCARG_ROOT /usr/local
    setenv PATH /usr/local/bin:$PATH
From bash or ksh: 
    export NCARG_ROOT=/usr/local
    export PATH=/usr/local/bin:$PATH
From sh: 
    NCARG_ROOT=/usr/local
    PATH=/usr/local/bin:$PATH
    export NCARG_ROOT
    export PATH
You should now be set for using NCL and/or NCAR Graphics. If you have any problems, or questions about installing NCL from source code or binaries, please send email to ncl-install@ucar.edu (you need to subscribe first).

Set the DISPLAY environment variable to indicate where to display graphics

This is not an NCL specific environment variable, but rather one that is used by any X11 Windows application that you run. For NCL or NCAR Graphics, it is needed when you display your graphics to an X11 window, or if you use ictrans, ctrans, or idt to view your NCGM files.

This variable must be set to the IP address or name of the machine you want to display your graphics on, for example "localhost:13.0" . If you are not running on a remote machine, then you can try setting it to ":0.0". Please contact your system administrator if you are not sure what to set it to.

For example, from C-shell (csh): 

    setenv DISPLAY :0.0
    setenv DISPLAY 128.117.14.12:0
    setenv DISPLAY localhost:13.0
From bash: 
    export DISPLAY=:0.0
    export DISPLAY=128.117.14.12:0
    export DISPLAY=localhost:13.0

Put a ".hluresfile" file in your home directory

In order to better customize the NCL graphical environment, we highly recommend that you copy a .hluresfile to your home directory. You can customize this file to your liking, but at a minimum, you can use this file to change the default font, the default color table, and the text function code.

Special instructions if you have an OPeNDAP-enabled version of NCL

[You don't need to worry about these instructions if you are not using OPeNDAP.]

OPeNDAP-enabled binaries require some libraries to be installed on your host computer:

  1. Secure Sockets Layer (SSL) library
  2. OPeNDAP libraries

Once you have these libraries, you may be required to set the environment variable LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH for Macs) to contain the directory where they are located on your host system in order for OPeNDAP-enabled versions of NCL to work properly.

Test your NCL/NCARG installation

For the commands below to work, you must have csh installed on your system. In most cases, csh is on your system by default. If it is not, and you are on a Linux system, you can try installing it with: 

  sudo apt-get install csh
or 

  yum install tcsh
(tcsh is an enhanced and compatible version of csh.)

If you are on Cygwin, see the instructions on the Cygwin page for installing csh.

You can quickly test if NCL is installed properly by typing: 

    ng4ex gsun01n
The ng4ex command will copy an NCL script called gsun01n.ncl into your current working directory, and run it through NCL. An X11 window should pop up with an XY plot drawn on it Click on this plot with your left mouse button to advance (and thus close) the frame.

Once this file is in your directory, you can run it yourself with: 

    ncl gsun01n.ncl
You can similarly test NCAR Graphics with: 
    ncargex cpex08


Special note for Linux/Mac systems

NCL was built using gcc/gfortran on some Linux and Mac systems. This causes a dependency on a file called "libgfortran.so.x".

If you have a different version of gfortran installed on your system than what NCL was built with, then you may get an error message that this file can't be found.

If you see this, then you can try five things:

  1. Try to find the libgfortran.so.x file that it is complaining about. If found, add this path to your LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH for Macs) environment variable.

    For example, if "libgfortran.so.3" is the file you need, and it is in /usr/local/lib, then look at the instructions below, depending on what shell you are running, and depending on whether LD_LIBRARY_PATH is already set: 

       env | grep LD_LIBRARY_PATH
    From csh or tcsh, if not set: 
        setenv LD_LIBRARY_PATH /usr/local/lib
    From csh or tcsh, if already set: 
        setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/usr/local/lib
    From bash or ksh, if not set: 
        export LD_LIBRARY_PATH=/usr/local/lib
    From bash or ksh, if already set: 
        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
    From sh, if not set: 
        LD_LIBRARY_PATH=/usr/local/lib
    export LD_LIBRARY_PATH
    From sh, if already set: 
        LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
    export LD_LIBRARY_PATH

  2. Install the "compat-libgfortran" runtime library. See one of these sites for starters:

  3. Check if this version of NCL comes with a special "ncl.static" file, and whether it works on your script: 
      which ncl.static
  ncl.static your_script.ncl
    If this works, then you may want to consider making this your default ncl: 
      mv $NCARG_ROOT/bin/ncl $NCARG_ROOT/bin/ncl.dynamic
  ln -s $NCARG_ROOT/bin/ncl.static $NCARG_ROOT/bin/ncl

  4. Install the version of gfortran that your version of NCL was built with. (It is possible to have multiple versions of gfortran installed on the same system without conflict.)

    It may then be necessary to set the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Macs) environment variable to the path of the "libgfortran.so.x" file.

  5. If all else fails, send email to the ncl-install list.

Note on compiling an NCAR Graphics program

If you are having problems compiling an NCAR Graphics program, and getting some undefined symbols like "s_cmp" and "s_copy", then you may be trying to link against GNU-compiled libraries, using a different compiler.

You can do this, but you need to help your compiler by linking in some additional system libraries. Try putting "-lgcc -lg2c" at the end of the compile line. For example: 

   ifort myProg.f -O -L/usr/local/lib -L/usr/X11R6/lib -lncarg -lncarg_gks \
   -lncarg_c -lXpm -lX11 -lXext -lg2c -lgcc


Special note on installing both NCL and NCAR Graphics

As of version 5.0.0, both NCL and NCAR Graphics are combined into one package, so you no longer need to install them separately.