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. This document assumes that you've already downloaded the gzipped tar file. If you haven't, see the main download page.

If you've read over this document and still have problems, then please send email to (you need to subscribe first). Read our posting guidelines first.

For Linux and MacOS systems, you have the choice of installing from OPeNDAP-enabled precompiled binaries or not. We recommend the non-OPenDAP binaries, if you don't need this functionality.

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

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

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

  1. Extract the file where you want the software to be installed.
  2. Set the NCARG_ROOT and PATH environment variables to point to where the software was installed.
  3. Set the DISPLAY environment variable to indicate where to display graphics (this step likely not needed)
  4. Put a ".hluresfile" file in your home directory.
  5. Test your NCL/NCARG installation.

Other notes:

Extract the file where you want the software to be installed

Decide where you want NCL/NCARG to be installed on your system. The compressed tar file contains executables, library files, and include files. When you extract the file, then, it will create directories "bin", "lib", and "include" in your current working directory.

For example, if you want to install the software to "/usr/local/ncl-6.3.0", then do the following:

    % mkdir /usr/local/ncl-6.3.0
    % cd /usr/local/ncl-6.3.0
    % tar -zxf ~/ncl_ncarg-6.3.0.MacOS_10.8_64bit_gcc471.tar.gz

Note: if the compressed tar file is not in your home directory, you will need to adjust the "~/" path accordingly.

Once this step is finished, you can remove the "ncl_ncarg-6.3.0.MacOS_10.8_64bit_gcc471.tar.gz" file.

Set the NCARG_ROOT and PATH environment variables to point to where the software was installed

In order to use the software, you must 1) set the NCARG_ROOT environment variable to the parent directory of where the software was installed, 2) add the $NCARG_ROOT/bin path to your PATH environment variable.

It is best to do this from the appropriate "dot" file in your home directory. A "dot" file is a hidden file which starts with a period. You must use the "-a" option with "ls" to see these files.

Which dot file you add these settings to depends on which UNIX shell you're using when you login. To determine your UNIX shell, there are several commands you can type on the UNIX command line. Here's a couple of them:

    ps -p $$
    echo $0
Here are some of the possible UNIX shells:

"sh" Bourne shell
"bash" Bourne-Again shell
"csh" C shell
"tcsh" TENEX shell (C shell compatible)
"ksh" Korn shell

To determine which dot file in your home directory to add the environment variables to, type:

    "ls -a ~/"
You might see files like ".bash_profile", ".cshrc", ".tcshrc", ".profile", etc.

Given your UNIX shell and using "/usr/local/ncl-6.3.0" as an example path, here's which "dot" file to edit and what lines to add (use a UNIX editor to make the changes):

csh/tcsh (the file might be ".cshrc" or ".tcshrc"):

    setenv NCARG_ROOT /usr/local/ncl-6.3.0
    setenv PATH $NCARG_ROOT/bin:$PATH
bash/ksh (the file might be ".bash_profile" or ".profile" or ".bashrc"):

    export NCARG_ROOT=/usr/local/ncl-6.3.0
    export PATH=$NCARG_ROOT/bin:$PATH
sh (the file might be ".bash_profile" or ".profile"):

    export NCARG_ROOT
    export PATH

You will need to logout and log back in for the changes to take effect.

Set the DISPLAY environment variable to indicate where to display graphics

Important note: this step should not generally be required! Your system should be setting this environment variable for you. If your DISPLAY is not set, then something is likely wrong with your login environment, and you should look into this.

However, if you are getting an error that DISPLAY is not set, and you have an older system or just can't seem to get anything else to work, then keep reading.

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, this environment variable 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
    setenv DISPLAY localhost:13.0
From bash:
    export DISPLAY=:0.0
    export DISPLAY=
    export DISPLAY=localhost:13.0

Put a ".hluresfile" file in your home directory

Note: this step is not as crucial for V6.1.x, since we changed several graphical defaults that we used to recommend that you set in this file.

However, if you want to customize your NCL graphical environment, then see this ".hluresfile" page. At a minimum, you may want to use this file to change the default color table.

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

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

You can similarly test NCAR Graphics. If you only plan to use NCL, it is not important that this command is successful.

    ncargex cpex08 -clean

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

NetCDF Version 4.1.x now comes with OPeNDAP support built into it, which makes building an OPeNDAP-enabled version of NCL much easier. As a result, the precompiled NCL binaries all have OPeNDAP support built in.

We also provide non-OPeNDAP enabled binaries for some LINUX and MacOS systems in case you have problems with the OPeNDAP versions.

If you run "ncl" and get error messages about missing files, please see these Linux, MacOSX, or Cygwin notes. You can also try downloading a non-OPenDAP enabled binary.