NCDUMP(1)

📦
version 4.10.1 · 3 versions
, in arch rolling, nixpkgs unstable, ubuntu stonking

🦋 ncdump(1) — UNIDATA UTILITIES 🦋

🌸 NAME 🌸

ncdump — Convert netCDF file to text form (CDL)

bestie, this is your girl from the UNIDATA UTILITIES manual, and she converts netCDF files into a text form called CDL 💖. That's literally the whole name, no cap.

✨ SYNOPSIS ✨

ncdump [-chistxwF] [-v var1,...]  [-b lang] [-f lang] [-l len] [-n name]
       [-p f_digits[,d_digits]] [-g grp1,...]  file

ncdump -k file

💅 DESCRIPTION 💅

okay so ncdump takes a specified netCDF file and spits out a text representation on standard output — and bestie, you can optionally leave out some or all of the variable data if you want 💖. That text representation is in a form called CDL (network Common Data form Language) and it can be viewed, edited, or even serve as input to ncgen, its companion program that can generate a binary netCDF file from a CDL file ✨. So fr fr, ncgen and ncdump are inverses — they transform the data representation between binary and text representations 🔁. For the full description of CDL and netCDF representations, go check the ncgen documentation, bestie 📚.

you can also use ncdump to figure out what kind of netCDF file you're dealing with — like which variant of the netCDF file format — using the -k option 👑.

if DAP support was enabled when ncdump was built, then the file name can be a DAP URL 🦋. That lets ncdump access data sources from DAP servers, including data in formats other than netCDF, no cap. And when you use it with DAP URLs, ncdump shows the translation from the DAP data model to the netCDF data model — iconic ✨.

think of ncdump as a simple browser for netCDF data files 💅. It can display the dimension names and lengths; variable names, types, and shapes; attribute names and values; and optionally, the values of data for all variables or selected variables in a netCDF file. For netCDF-4 files, groups and user-defined types are also included in the ncdump output. periodt 💖.

when a data value equals a variable's _FillValue attribute — which is meant to represent data that hasn't been written yet — ncdump shows it as _ 💀. If a variable has no _FillValue attribute, then the default fill value for that variable's type gets used, unless the variable is of byte type. iykyk.

ncdump has a default display format for each type of netCDF data, but bestie, you can change it if you define a C_format attribute for a netCDF variable 🌈. In that case, ncdump will use the C_format attribute to format each value, slay. For example, if floating-point data for the netCDF variable Z is known to be accurate to only three significant digits, it would be appropriate to use the variable attribute

Z:C_format = "%.3g"

✨ OPTIONS ✨

okay bestie, this is the part where it gets good 🎀 every single one of these little flags changes what ncdump shows you, so let's go one by one, no skips, we're covering all of them 💅

  • -c — shows you the values of coordinate variables (those are the 1D variables that share a name with a dimension, iykyk) plus the declarations of every dimension, variable, attribute value, group, and user-defined type. 🦋 the data values of non-coordinate variables? nope, not included. this is usually the whole vibe for a quick lil' look at the structure and contents of a netCDF file, fr fr.
  • -h — header info only, nothing else. 🙈 you get just the declarations for the dimensions, variables, attributes, groups, and user-defined types of the input file — zero data values for any variable. it's literally identical to using -c, except the values of coordinate variables don't show up. (and heads up: at most one of -c or -h may be present.)
  • -v var1,... — now your output includes data values for the variables you name, on top of the declarations of all dimensions, variables, and attributes. 🌸 you gotta specify one or more variables by name in the comma-delimited list after this option, and the whole list has to be a single argument to the command — so it can't have unescaped blanks or any other whitespace characters, periodt. the named variables have to be valid netCDF variables in the input-file. a variable inside a group in a netCDF-4 file can be specified with an absolute path name, like /GroupA/GroupA2/var. use a relative path name like var or grp/var and it specifies all matching variable names in the file. the default — without this option and with no -c or -h around — is to include data values for all variables in the output. 💖
  • -b [c|f] — a lil' brief annotation, in the form of a CDL comment (text starting with the characters //), gets dropped into the data section of the output for each row of data, so you can identify data values in multidimensional variables. 🧚 if lang begins with C or c, then C language conventions are used (zero-based indices, last dimension varying fastest). if lang begins with F or f, then Fortran language conventions are used (one-based indices, first dimension varying fastest). either way, the data is presented in the same order — only the annotations differ. this one's lowkey useful for browsing through large volumes of multidimensional data. 📚
  • -f [c|f] — full annotations this time, as trailing CDL comments (text beginning with the characters //) for every data value (except individual characters in character arrays), all up in the data section. 🔥 if lang begins with C or c, C language conventions are used. if lang begins with F or f, Fortran language conventions are used. again, either way the data is presented in the same order — only the annotations differ. this one is perfect for piping data into other filters, since each data value appears on its own separate line, fully identified. 👑 (and yes bestie: at most one of -b or -f may be present.)
  • -l length — changes the default maximum line length (80) used when formatting lists of non-character data values. ✨
  • -n name — CDL needs a name for a netCDF file, for use by ncgen -b when it's generating a default netCDF file name. by default, ncdump builds that name from the last component of the file name of the input netCDF file, stripping off any extension it has. use -n to specify a different name. 💫 and like — yes, the output file name used by ncgen -b can be specified, but it may be wise to have ncdump change the default name, so you don't inadvertently overwrite a precious, valuable netCDF file when you're out here using ncdump, editing the resulting CDL file, and then running ncgen -b to generate a new netCDF file from the edited CDL file. 🙈 protect your files, bestie.
  • -p float_digits[,double_digits] — specifies the default precision (number of significant digits) to use when displaying floating-point or double precision data values for attributes and variables. ⭐ if specified, this value overrides the value of the C_format attribute, if any, for a variable. floating-point data gets displayed with float_digits significant digits. if double_digits is also specified, double-precision values are displayed with that many significant digits. with no -p specifications at all, floating-point and double-precision data are displayed with 7 and 15 significant digits respectively. 🌈 CDL files can be made smaller if you don't need all that precision. if you specify both floating-point and double precisions, the two values must appear separated by a comma (no blanks!) as one single argument to the command. (and to represent every last bit of precision in a CDL file for all possible floating-point values, you'd need -p 9,17.)
  • -k — shows you the kind of netCDF file the pathname references, one of classic, 64-bit offset, netCDF-4, or netCDF-4 classic model. 💜 okay history lesson: before version 3.6, there was only one kind of netCDF file, designated classic (also known as format variant 1). large file support introduced another variant, designated 64-bit offset (known as format variant 2). NetCDF-4 uses a third variant, netCDF-4 (format variant 3). and there's yet another format variant, netCDF-4 classic model (format variant 4), which is restricted to the features supported by the netCDF-3 data model but represented using the HDF5 format — so an unmodified netCDF-3 program can read or write the file just by relinking with the netCDF-4 library. 🫶 the string that comes out of the -k option can be handed over as the value of the -k option to ncgen(1) to specify exactly what kind of netCDF file to generate, whenever you want to override the default inferred from the CDL.
  • -s — outputs special virtual attributes that give you performance-related info about the file format and variable properties for netCDF-4 data. 🦋 these special virtual attributes aren't actually part of the data — they're just a convenient way to display miscellaneous properties of the data in CDL (and eventually NcML). they include _ChunkSizes, _DeflateLevel, _Endianness, _Fletcher32, _Format, _NoFill, _Shuffle, and _Storage. lemme break it down:
    • _ChunkSizes is a list of chunk sizes for each dimension of the variable.
    • _DeflateLevel is an integer between 0 and 9 inclusive, if compression was specified for the variable.
    • _Endianness is either little or big, depending on how the variable was stored when it was first written.
    • _Fletcher32 is true if the checksum property was set for the variable.
    • _Format is a global attribute specifying the netCDF format variant — one of classic, 64-bit offset, netCDF-4, or netCDF-4 classic model.
    • _NoFill is true if the persistent NoFill property was set for the variable when it was defined.
    • _Shuffle is true if use of the shuffle filter was specified for the variable.
    • _Storage is contiguous or compact or chunked, depending on how the variable's data is stored.
  • -t — controls display of time data, if it's stored in a variable that uses a udunits compliant time representation like days since 1970-01-01 or seconds since 2009-03-15 12:01:17, or a variable identified in a "bounds" attribute of such a time variable, or a numeric attribute of a time variable. 🕐 if this option is specified, time data values get displayed as human-readable date-time strings instead of numerical values, interpreted in terms of a calendar variable attribute, if one is specified. for numeric attributes of time variables, the human-readable time value is displayed after the actual value, in an associated CDL comment. calendar attribute values interpreted with this option include the CF Conventions values gregorian or standard, proleptic_gregorian, noleap or 365_day, all_leap or 366_day, 360_day, and julian. 💅
  • -i — same as the -t option, except it outputs time data as date-time strings with the ISO-8601 standard T separator, instead of a blank. ✨
  • -g grp1,... — for netCDF-4 files, your output includes data values only for the specified groups. 🌸 you must specify one or more groups by name in the comma-delimited list after this option, and the list has to be a single argument to the command. the named groups have to be valid netCDF groups in the input-file. a group in a netCDF-4 file can be specified with an absolute or relative path name. using a relative path name specifies all matching group names in the file. the default — without this option and with no -c or -h — is to include data values for all groups in the output. 💖
  • -w — for file names that request remote access using DAP URLs, access data with client-side caching of entire variables. 🫶
  • -x — outputs XML (NcML) instead of CDL. 🌈 note that the NcML does not include data values. also, the NcML output option currently only works for netCDF classic model data. (so don't come crying to me if it doesn't do the thing on your fancy netCDF-4 file, bestie 😭)
  • -F — when used with -s, displays filter information using the generic _Filter and _Codecs virtual attributes instead of the legacy per-filter attributes _Fletcher32, _Shuffle, and _Deflate. 👑 the _Codecs attribute lists the names of all filters applied to a variable (e.g., shuffle, deflate, fletcher32, szip); the _Filter attribute provides the corresponding HDF5 filter identifier and any parameters. filters that may appear include the built-in HDF5 filters (deflate/zlib, shuffle, fletcher32, szip) as well as any additional filters provided by installed HDF5 plugins, such as bzip2 (filter ID 307) or Zstandard (filter ID 32015). 🔥

✨ EXAMPLES ✨

Okay bestie, here's where it gets fun — real commands you can actually steal 💅

  • Wanna peek at the structure of the data in the netCDF file foo.nc? Say literally no more:
ncdump -c foo.nc
  • Want an annotated CDL version of the whole structure and the data in foo.nc, with the annotations using C-style indexing? Bet:
ncdump -b c foo.nc > foo.cdl
Not me redirecting that straight into foo.cdl with >... the way that shell operator is carrying this whole example 🫶
  • Only want data for the variables uwind and vwind from foo.nc, and you want the floating-point data shown with just three significant digits of precision? Iconic, say less:
ncdump -v uwind,vwind -p 3 foo.nc
  • And for the full main-character treatment: a fully-annotated listing (that's one data value per line, no cap) of the data for the variable omega, using Fortran conventions for indices, and changing the netCDF dataset name in the resulting CDL file to omega:
ncdump -v omega -f fortran -n omega foo.nc > Z.cdl

🌈 SEE ALSO 🌈

Go hang out with these other pages when you're done here:

💀 BUGS 💀

Okay so these are the known little gremlins lurking in here — not me being dramatic, this is straight from the page fr fr:

  • Character arrays that contain a null-byte get treated like C strings, which means no characters after the null byte appear in the output. Gone. Poof. That's just how it is, sorry bestie 😭
  • Multidimensional character string arrays are not handled well, because the CDL syntax for breaking a long character string into several shorter lines is weak. It's giving "we tried our best" 🙈
  • There should be a way to specify that the data should be displayed in record order — like, with all the values for record variables together that have the same value of the record dimension. But there isn't one yet. Lowkey a wishlist item 👑

and that's the whole page, bestie!! 🦋✨ You just read the manual page for Release 4.10.1, dated 2026-03-11, for NCDUMP(1). Go dump some netCDF files, you absolute icon, I'm obsessed with you 💖🎀🌸

📦 where this page comes from