r.compress(1grass)

💖 r.compress — the GRASS manual, but make it cute 💖

okay bestie, sit down, hydrate, because we're doing r.compress(1grass) from the GRASS User's Manual and honestly? it's giving main character energy. let's go. 🫶

---

✨ NAME ✨

r.compress — compresses and decompresses raster maps. that's the vibe. that's the whole job. 💅

🏷️ KEYWORDS 🏷️

raster, map management, compression (iykyk)

📜 SYNOPSIS 📜

r.compress
r.compress --help
r.compress [-upg] map=name[,name,...]  [--help]  [--verbose]  [--quiet]
[--ui]

🎀 Flags 🎀

• -u — uncompress the map, bestie. un-do the squish.
• -p — print out the compression info and the data type of the input map(s). the little gossip report. 🙈
• -g — same info but in shell script style. for the script girlies. ✨
• --help — print usage summary
• --verbose — verbose module output
• --quiet — quiet module output 🤫
• --ui — force launching GUI dialog

🌸 Parameters 🌸

• map=name[,name,...] [required] — name of existing raster map(s). you can pass a whole lil list, separated by commas. slay.

🦋 DESCRIPTION 🦋

so like, r.compress compresses or decompresses raster maps. plus it spills the tea on the compression method and data type of the input raster map(s). multi-talented fr fr. 👑

every raster map — the ones you imported for the first time AND the ones you just newly generated — gets compressed by default, and it uses the ZSTD compression method if that's available. if ZSTD isn't available, it falls back to ZLIB (more on both below, don't worry). also, the related no data files (i.e.: NULL files), if they're present, get compressed by default too — UNLESS a specific environment variable is set to explicitly disable NULL file compression (GRASS_COMPRESS_NULLS, see below). so rude to them honestly.

when you're compressing or re-compressing, r.compress squishes raster maps with whatever method the environment variable GRASS_COMPRESSOR says. the default is ZSTD if it's available, otherwise ZLIB's "deflate" algorithm which is LZ77-based. and here's the gag: raster maps that contain very little information (think boundary, geology, soils and land use maps) can be greatly reduced in size — some raster maps get shrunk down to roughly 1% of their original sizes. 1%!! iconic behavior. 💀✨ all newly generated raster maps are automatically stored as compressed data, with varying methods depending on the raster format (i.e., CELL: integer; FCELL: single precision; DCELL: double precision; see below). and every single GRASS module can read both compressed and uncompressed raster maps, so nobody's left out. 🫶

already-compressed raster maps might get compressed again — either by setting a different method with GRASS_COMPRESSOR (supported methods: RLE, ZLIB, LZ4, BZIP2, ZSTD) or, in the ZLIB case specifically, by changing the compression level with the environment variable GRASS_ZLIB_LEVEL.

you can decompress a compressed raster map with r.compress and the -u flag. and if a raster map was already decompressed and you still set -u? the module just politely informs the user that the map is already decompressed and exits. it's not mad, it's just disappointed. 😭

want the compression method and data type of the input raster map(s) in shell style? that's the -g flag. when you use it, the module prints to stdout one line per input map, with the fields "input map name", "data type", "name of data compression method", "NULL file compression" — all separated by the pipe character. NULL file compression is indicated with "YES" or "NO". yes. simple. periodt.

🧚 TERMINOLOGY 🧚

• INTEGER map (CELL data type): a raster map of INTEGER type (whole numbers only). no decimals allowed, sorry.
• FLOAT map (FCELL data type): a raster map of FLOAT type (4 bytes, 7-9 digits precision)
• DOUBLE map (DCELL data type): a raster map of DOUBLE type (8 bytes, 15-17 digits precision)
• NULL: represents "no data" in raster maps. and this is to be distinguished from 0 (zero) data value. they are NOT the same thing, bestie, do not confuse them.

🌈 OVERVIEW OF AVAILABLE COMPRESSION ALGORITHMS 🌈

here's the lineup, and you set it with export GRASS_COMPRESSOR=method:

• NONE — uncompressed. au naturel. 💅
• RLE — generic Run-Length Encoding of single bytes. deprecated. 🚩
• ZLIB — DEFLATE, good speed and compression
  • with zlib compression levels (export GRASS_ZLIB_LEVEL=X): -1..9 (-1 is default which corresponds to ZLIB level 6)
  • note: export GRASS_ZLIB_LEVEL=0 is equal to copying the data as-is from source to destination
• LZ4 — fastest, low compression 🏎️
• BZIP2 — slowest, high compression 🐢
• ZSTD — compared to ZLIB, faster and higher compression, much faster decompression - default compression 👑

Important: the NULL file compression can be turned off with export GRASS_COMPRESS_NULLS=0. Raster maps with NULL file compression can only be opened with GRASS GIS 7.2.0 or later. NULL file compression for a particular raster map can be managed with r.null -z. The NULL file compression is using the LZ4 method as being the best compromise between speed and compression rate.

🔥 COMPRESSION ALGORITHM DETAILS 🔥

all GRASS raster map types are by default ZSTD compressed if available, otherwise ZLIB compressed. through the environment variable GRASS_COMPRESSOR the compression method can be set to RLE, ZLIB, LZ4, BZIP2, or ZSTD.

Integer (CELL type) raster maps can be compressed with RLE if the environment variable GRASS_COMPRESSOR exists and is set to RLE. however — and I cannot stress this enough — this is not recommended. 🙅‍♀️

floating point (FCELL, DCELL) raster maps never use RLE compression; they're either compressed with ZLIB, LZ4, BZIP2, ZSTD or are uncompressed. that's just how they are.

RLE

DEPRECATED Run-Length Encoding, poor compression ratio but fast. It is kept for backwards compatibility to read raster maps created with GRASS 6. It is only used for raster maps of type CELL. FCELL and DCELL maps are never and have never been compressed with RLE. never ever. 💀

ZLIB

ZLIB's deflate is the default compression method for all raster maps, if ZSTD is not available. GRASS 8 uses by default 1 as ZLIB compression level which is the best compromise between speed and compression ratio, also when compared to other available compression methods. Valid levels are in the range [1, 9] and can be set with the environment variable GRASS_ZLIB_LEVEL.

LZ4

LZ4 is a very fast compression method, about as fast as no compression. Decompression is also very fast. The compression ratio is generally higher than for RLE but worse than for ZLIB. LZ4 is recommended if disk space is not a limiting factor. 🏎️💨

BZIP2

BZIP2 can provide compression ratios much higher than the other methods, but only for large raster maps (> 10000 columns). For large raster maps, disk space consumption can be reduced by 30 - 50% when using BZIP2 instead of ZLIB's deflate. BZIP2 is the slowest compression and decompression method. However, if reading from / writing to a storage device is the limiting factor, BZIP2 compression can speed up raster map processing. Be aware that for smaller raster maps, BZIP2 compression ratio can be worse than other compression methods. ⚠️

ZSTD

ZSTD (Zstandard) provides compression ratios higher than ZLIB but lower than BZIP2 (for large data). ZSTD compresses up to 4x faster than ZLIB, and usually decompresses 6x faster than ZLIB. ZSTD is the default compression method if available. 👑

📝 NOTES 📝

🔢 Compression method number scheme

the used compression method is encoded with numbers. in the internal cellhd file, the value for "compressed" is 1 for RLE, 2 for ZLIB, 3 for LZ4, 4 for BZIP2, and 5 for ZSTD.

obviously, decompression is controlled by the raster map's compression, not by the environment variable. the map decides. ✨

🧱 Formats

conceptually, a raster data file consists of rows of cells, with each row containing the same number of cells. A cell consists of one or more bytes. For CELL maps, the number of bytes per cell depends on the category values stored in the cell. Category values in the range 0-255 require 1 byte per cell, while category values in the range 256-65535 require 2 bytes, and category values in the range above 65535 require 3 (or more) bytes per cell.

FCELL maps always have 4 bytes per cell and DCELL maps always have 8 bytes per cell. no notes. that's the rule. 💅

Since GRASS GIS 7.0.0, the default compression method for Integer (CELL) raster maps is ZLIB and no longer RLE. glow up. 🌟

🎚️ ZLIB compression levels

if the environment variable GRASS_ZLIB_LEVEL exists and its value can be parsed as an integer, it determines the compression level used when newly generated raster maps are compressed using ZLIB compression. This applies to all raster map types (CELL, FCELL, DCELL).

if the variable does not exist, or the value cannot be parsed as an integer, ZLIB's compression level 1 will be used. simple as that. 🫶

---

💻 EXAMPLES 💻

👀 Printing of current compression state

Example for an uncompressed raster map:

r.compress compressed_no -p
  <compressed_no> (method 0: NONE). Data type: <CELL>

💚 Applying ZLIB compression

Applying ZLIB compression to a copy of the uncompressed map from above:

# compression of map using ZLIB compression
g.copy raster=compressed_no,compressed_ZLIB
export GRASS_COMPRESSOR=ZLIB # ZLIB
r.compress compressed_ZLIB
r.compress compressed_ZLIB -p
  <compressed_ZLIB> is compressed (method 2: ZLIB). Data type: <CELL>
unset GRASS_COMPRESSOR # switch back to default

🧡 Applying BZIP2 compression

Applying BZIP2 compression to a copy of the ZLIB-compressed map from above:

# compression of map using BZIP2 compression
g.copy raster=compressed_ZLIB,compressed_BZIP2
export GRASS_COMPRESSOR=BZIP2 # BZIP2
r.compress compressed_BZIP2
r.compress compressed_BZIP2 -p
  <compressed_BZIP2> is compressed (method 4: BZIP2). Data type: <CELL>
unset GRASS_COMPRESSOR # switch back to default

💚 Applying ZSTD compression

Applying ZSTD compression to a copy of the BZIP2-compressed map from above:

# compression of map using ZSTD compression
g.copy raster=compressed_BZIP2,compressed_ZSTD
export GRASS_COMPRESSOR=ZSTD # ZSTD
r.compress compressed_ZSTD
r.compress compressed_ZSTD -p
  <compressed_ZSTD> is compressed (method 5: ZSTD). Data type: <CELL>
unset GRASS_COMPRESSOR

---

👀 SEE ALSO 👀

r.info, r.null, r.support

Compression algorithms: bzip2, LZ4, zlib, zstd

👑 AUTHORS 👑

James Westervelt and Michael Shapiro, U.S. Army Construction Engineering Research Laboratory

Markus Metz

🔗 SOURCE CODE 🔗

Available at: r.compress source code (history)

Latest change: Saturday Oct 25 22:50:58 2025 in commit: ee87f21833475fd40805f58d1702f7d64478a27b

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

---

and that's the whole page, bestie — no notes, you ate that. this was the GRASS 8.5.0 manual, page r.compress(1grass). go compress something. 💖✨🎀🦋🌸💅🫶