Getting Started With NCL

This list is for people who are new to NCL and are not sure where to start first.

Note that NCL and NCAR Graphics are shipped as one package. The instructions below refer to NCL, but they apply for NCAR Graphics as well.

Information on setting up NCL on your system

Information on learning NCL

Where to get help and training

How to set up your NCL environment

Before you can use NCL, you must do four things:

  1. Set the NCARG_ROOT environment variable.
  2. Add $NCARG_ROOT/bin to your UNIX search path.
  3. Make sure your DISPLAY environment variable is set correctly.
  4. Put a .hluresfile file in your home directory.

  1. Set the NCARG_ROOT environment variable.

    Set the NCARG_ROOT environment variable to the root directory of where the NCL software is installed. For example, if NCL was installed to /usr/local/bin and /usr/local/lib, then NCARG_ROOT should be set to /usr/local.

    To set this environment variable, you must know what kind of UNIX shell environment you're running. Usually, typing:

         echo $SHELL
    on the UNIX command line will tell you this information. If it says something like "/bin/tcsh" or "/bin/csh", then you can set the environment variable as follows (using "/usr/local" as an example):

        setenv NCARG_ROOT /usr/local
    If it says "/bin/bash" or "/bin/ksh", then use:

        export NCARG_ROOT=/usr/local
    If it says "/bin/sh", then use these two lines:

        export NCARG_ROOT
    To keep from having to type these commands in every time you login, it is best to add these lines (or line) to the appropriate ".*" file in your home directory. (The ~/.cshrc or ~/.bashrc are two examples; be sure to use the one appropriate for the shell environment you are running.)

  2. Add $NCARG_ROOT/bin to your search path.

    This is necessary so that when you run NCL, your system knows where to find the "ncl" executable.

    First, you need to find out where your current UNIX path is being set up. This is usually done in one of the ".*" files in your home directory. You can search for a path setting by typing:

        grep -i path ~/.*
    If you see something like one of these lines:
        set path=(~/bin /usr/bin /bin/etc /usr/X11R6/bin /usr/local/bin)
        export PATH=~/bin:/usr/bin:/bin/etc:/usr/X11R6/bin:/usr/local/bin
    then you can edit this file, and add "$NCARG_ROOT/bin" to the list of paths:

        set path=(~/bin /usr/bin /bin/etc /usr/X11R6/bin /usr/local/bin $NCARG_ROOT/bin)
        export PATH=~/bin:/usr/bin:/bin/etc:/usr/X11R6/bin:/usr/local/bin:$NCARG_ROOT/bin

  3. Set the DISPLAY environment variable.

    In order to run NCL scripts that display their output directly to an X11 window, you need to have your DISPLAY environment variable set correctly. Usually this is set for you by your system.

    You can test this by running an X application to see if it pops up on your screen. A good test X application is "xclock". At the UNIX command line, type:

    If clock pops up on your screen, then your DISPLAY environment variable is already being set correctly.

    If not, and you get an error message like:

         Error: Can't open display
    then either your DISPLAY environment variable is not set correctly, or you are logging in remotely from another system using something like "ssh" and haven't turned on X11 fowarding, which you can do with "ssh -X" or "ssh -Y".

    If you are still not sure what to do at this point, then subscribe to the "ncl-install" email list and email your question to

  4. 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 may want to change the default color table and the default size of the X11 window.

How to run NCL

Once your NCL environment has been correctly set up, you are ready to run NCL. If you already have an NCL script, say "omega.ncl", you can run it by typing:

    ncl omega.ncl
If you don't have an NCL script to run, and you would like to run a sample one, then type:

    ng4ex gsun01n
This should copy an NCL script called "gsun01n.ncl" to your current working directory and run NCL on it. Running this example requires that you have your DISPLAY environment variable set correctly.