NCL Website header
NCL Home > Documentation > Language

NCL environment variables

There's only one environment variable you are required to set before running NCL, and that is NCARG_ROOT. This should be set to the parent directory (and not the "bin" directory that contains the "ncl" executable) of where the NCL software was installed. NCL uses the NCARG_ROOT environment variable to determine where various parts of the NCL software is installed, like the map databases, the color tables, the fonts, and the example programs. All users must set this environment variable before they can run NCL, and the person who installed NCL on your system should be able to tell you what to set it to.

More advanced NCL users may decide to create their own color maps, or move parts of the NCL installation to somewhere other than under NCARG_ROOT, in which case you can use additional environment variables to indicate the new location of these files.

For example, if you decide to create your own color tables and put them somewhere, you can use the NCARG_COLORMAP_PATH environment variable to indicate the path to these color tables, but yet still keep the NCL standard color table path.

Another example is if you decide to install the RANGS/GSHHS high-resolution map database. This database is recognized by NCL and will give you access to high-resolution coastal maps. The default location that NCL expects it in is the directory $NCARG_ROOT/lib/ncarg/database/rangs. However, if you want to put it somewhere else, you can do this and then set the environment variable NCARG_RANGS to point to this new location.

All of the NCL environment variables are listed below. For some of these environment variables, you can get their default value by executing the ncargpath program with a keyword from the shell prompt, or calling the ncargpath function from an NCL script. You need to provide a keyword argument in both cases.

Below is a list of all NCL environment variables, and whether they have an ncargpath keyword for getting its default value.

DISPLAY (no keyword)
This is not an NCL specific environment variable, but rather one that is used by any X11 Windows application that you run. For NCL, 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".

Default: Depends on your system, it may already be set for you.

GRAPHCAP (keyword graphcap)
This environment variable is used to select the graphcap for ctrans to use.

Default: none
If this environment variable is not set, then command line flags must be used.

NCARG_GKS_OUTPUT (keyword gks_output)
This environment variable is used to indicate the default name of the metafile the ncgm workstation outputs to.

Default: gmeta

NCARG_GKS_PSOUTPUT (no keyword)
This environment variable is used to indicate the default name of the PostScript the PS workstation outputs to. Stdout is allowed.

Default: gmeta1.ps

NCARG_USRRESFILE (keyword usrresfile)
This environment variable is used to specify the user's HLU resource file. This file can be used to specify resources for all HLU programs.

Default: ~/.hluresfile
Note: This default is configurable at compilation time, so your system administrator may have changed it.

NCARG_ROOT (keyword root)
This environment variable is used to indicate where the "root" of the NCL install tree is. If things are installed properly, most of the other environment variables are determined relative to the value of this variable.

Default: /usr/local
Note: This default is configurable at compilation time, so your system administrator may have changed it.

NCARG_BIN (keyword bin)
This environment variable is used to indicate the location of the "bin" directory in the NCL install tree.

Default: $(NCARG_ROOT)/bin

NCARG_MAN (keyword man)
This environment variable is used to indicate the location of the "man" pages in the NCL install tree.

Default: $(NCARG_ROOT)/man

NCARG_INCLUDE (keyword include)
This environment variable is used to indicate where the NCL "include" files are installed.

Default: $(NCARG_ROOT)/include

NCARG_LIB (keyword lib)
This environment variable is used to indicate where the NCL libraries are installed.

Default: $(NCARG_ROOT)/lib

NCARG_NCARG (keyword ncarg)
This environment variable is used to indicate the locations of the supplemental directories, like examples, databases, resource files, and so on.

Default: $(NCARG_LIB)/ncarg

NCARG_COLORMAP_PATH (no keyword)
This environment variable can be used to set up a list of paths for locations of color tables, including NCL's standard color table location. This allows to you to put your own color tables in your own directory, but still be able to find NCL's color tables. See "create your own color tables" for an example.

Default: Default: $(NCARG_NCARG)/colormaps

NCARG_COLORMAPS (keyword colormaps)
This environment variable is used to indicate the default location of NCL's color tables.

Default: Default: $(NCARG_NCARG)/colormaps

NCARG_RANGS (keyword rangs)
This environment variable is used to indicate the location of the RANGS/GSHHS database. This database is a large one, and is not included by default with NCL.

Default: Default: $(NCARG_NCARG)/rangs

NCARG_CONFIG (keyword config)
This environment variable is used to indicate where the NCL config files are installed. (These config files are only installed if NCL is installed from source, they are not needed for a binary installation.)

Default: $(NCARG_NCARG)/config

NCARG_DATABASE (keyword database)
This environment variable is used to indicate where the NCL database files are installed (map databases etc).

Default: $(NCARG_NCARG)/database

NCARG_DATA (keyword data)
This environment variable is used to indicate where the data files for the NCL and HLU examples are installed.

Default: $(NCARG_NCARG)/data

NCARG_FONTCAPS (keyword fontcaps)
This environment variable is used to indicate where the fontcaps are installed.

Default: $(NCARG_NCARG)/fontcaps

NCARG_GRAPHCAPS (keyword graphcaps)
This environment variable is used to indicate where the graphcaps are installed.

Default: $(NCARG_NCARG)/graphcaps

NCARG_HLUEX (keyword hluex)
This environment variable is used to indicate where the C and Fortran HLU examples are installed.

Default: $(NCARG_NCARG)/hluex

NCARG_NCLEX (keyword nclex)
This environment variable is used to indicate where the NCL examples are installed.

Default: $(NCARG_NCARG)/nclex

NCARG_RESFILES (keyword resfiles)
This environment variable is used to indicate where the resource files for the NCL and HLU examples are installed.

Default: $(NCARG_NCARG)/resfiles

NCARG_EXAMPLES (keyword examples)
This environment variable is used to indicate where the low-level examples are installed (may not be included with the NCL binary).

Default: $(NCARG_NCARG)/examples

NCARG_TESTS (keyword tests)
This environment variable is used to indicate where the low-level test examples are installed (may not be included with the NCL binary).

Default: $(NCARG_NCARG)/tests

NCARG_TUTORIAL (keyword tutorial)
This environment variable is used to indicate where the low-level tutorial examples are installed (may not be included with the NCL binary).

Default: $(NCARG_NCARG)/tutorial

NCARG_XAPP (keyword xapp)
This environment variable is used to indicate where the NCL X application resource files are installed.

Default: $(NCARG_NCARG)/xapp

NCARG_SYSRESFILE (keyword sysresfile)
This environment variable is used to indicate where the system resource file is installed.

Default: $(NCARG_NCARG)/sysresfile

NCARG_SYSAPPRES (keyword sysappres)
This environment variable is used to indicate where the NCL Application resource files are installed.

Default: $(NCARG_NCARG)/sysappres

NCL_DEF_LIB_DIR (no keyword)
If this environment variable is set to a valid directory pathname, NCL will look in this directory for dynamic shared objects (*.so files) for NCL to load automatically. These *.so files are ones that should have been created by running WRAPIT or "wrapit77".

In particular this means that, in order to invoke your new function or procedure, you should not prepend SO_NAME:: to the function or procedure name as is required when you use the "external" statement to load a *.so file. NCL will try to load everything in the directory specified by NCL_DEF_LIB_DIR, so you will get warning messages about files in the directory that are not shared objects.

For more information, see the "Loading the shared object using an environment variable" section in the WRAPIT document, or the section "Loading default scripts and shared libraries" in the Reference Manual.

Default: None

NCL_DEF_SCRIPTS_DIR (no keyword)
If this environment variable is set to a valid directory pathname, NCL will attempt to load all files with the file extension ".ncl" found within this directory, as if each were invoked by the "load" statement.

The scripts are loaded in the order in which they appear in the UNIX directory entries structure, so if one file depends on another, you may run into problems.

See the section "Loading default scripts and shared libraries" in the Reference Manual for more information.

Default: None

NCL_GRIB_PTABLE_PATH (no keyword)
An NCL GRIB parameter table file is a text file that specifies one or more distinct parameter tables for NCL to use when reading GRIB files. Setting this environment variable to the pathname of the file causes NCL to parse it and incorporate its parameter tables when first asked to open a GRIB file. Optionally, NCL_GRIB_PTABLE_PATH may be set to a directory path, in which case all files in the directory with the suffix '.gtb' are opened as parameter tables.

See the section "User-defined GRIB1 parameter tables" in the Reference Manual for more information.

Default: None

NCL_NO_SYSTEM_PAGER (no keyword)
By default, system pages its output for the convenience of the user. If you have the PAGER environment variable set, that value is used for paging; if it's not set, the pager "more" is used. If this behavior is not desired, paging may be turned off by setting this environment variable.

Default: None

NIO_GRIB2_CODETABLES (keyword grib2_codetables)
This environment variable indicates the location of the GRIB2 code tables.

Default: $NCARG_ROOT/lib/ncarg/grib2_codetables

PAGER (no keyword)
This is not an NCL specific environment variable, but rather one that can be used by other UNIX applications. In NCL land, this setting is used to determine how the output from procedures print and system should be paged.

Default: "more"

PSADILOOKUP_PATH (no keyword)
This environment variable indicates the location of the "psadilookup.dat" file needed by the functions. rip_cape_3d and rip_cape_2d.

Default: $NCARG_ROOT/lib/ncarg/data/asc

TMPDIR (keyword tmp)
This environment variable indicates what directory NCL should use for temporary files.

Default: /tmp
Note: This default is configurable at compilation time, so your system administrator may have changed it.