xzcat is equivalent to "xz --decompress --stdout" .

lzma is equivalent to "xz --format=lzma" .

unlzma is equivalent to "xz --format=lzma --decompress" .

lzcat is equivalent to "xz --format=lzma --decompress --stdout" .

When writing scripts that need to decompress files, it is recommended to always use the name xz with appropriate arguments ( "xz -d" or "xz -dc" ) instead of the names unxz and xzcat . .

xz compresses or decompresses each file according to the selected operation mode. If no files are given or file is - , xz reads from standard input and writes the processed data to standard output. xz will refuse (display an error and skip the file ) to write compressed data to standard output if it is a terminal. Similarly, xz will refuse to read compressed data from standard input if it is a terminal.

Unless --stdout is specified, files other than - are written to a new file whose name is derived from the source file name:

If the target file already exists, an error is displayed and the file is skipped.

Unless writing to standard output, xz will display a warning and skip the file if any of the following applies:

After successfully compressing or decompressing the file , xz copies the owner, group, permissions, access time, and modification time from the source file to the target file. If copying the group fails, the permissions are modified so that the target file doesn't become accessible to users who didn't have permission to access the source file . xz doesn't support copying other metadata like access control lists or extended attributes yet.

Once the target file has been successfully closed, the source file is removed unless --keep was specified. The source file is never removed if the output is written to standard output or if an error occurs.

Sending SIGINFO or SIGUSR1 to the xz process makes it print progress information to standard error. This has only limited use since when standard error is a terminal, using --verbose will display an automatically updating progress indicator. .

Especially users of older systems may find the possibility of very large memory usage annoying. To prevent uncomfortable surprises, xz has a built-in memory usage limiter, which is disabled by default. While some operating systems provide ways to limit the memory usage of processes, relying on it wasn't deemed to be flexible enough (for example, using ulimit (1) to limit virtual memory tends to cripple mmap (2)).

The memory usage limiter can be enabled with the command line option --memlimit=limit. Often it is more convenient to enable the limiter by default by setting the environment variable TRANSLATORS: Don't translate the uppercase XZ_DEFAULTS.
It's a name of an environment variable.
XZ_DEFAULTS , for example, XZ_DEFAULTS=--memlimit=150MiB . It is possible to set the limits separately for compression and decompression by using --memlimit-compress= limit and --memlimit-decompress=limit. Using these two options outside XZ_DEFAULTS is rarely useful because a single run of xz cannot do both compression and decompression and --memlimit= limit (or -M limit ) is shorter to type on the command line.

If the specified memory usage limit is exceeded when decompressing, xz will display an error and decompressing the file will fail. If the limit is exceeded when compressing, xz will try to scale the settings down so that the limit is no longer exceeded (except when using --format=raw or --no-adjust ). This way the operation won't fail unless the limit is very small. The scaling of the settings is done in steps that don't match the compression level presets, for example, if the limit is only slightly less than the amount required for "xz -9" , the settings will be scaled down only a little, not all the way down to "xz -8" . .

It is possible to insert padding between the concatenated parts or after the last part. The padding must consist of null bytes and the size of the padding must be a multiple of four bytes. This can be useful, for example, if the .xz file is stored on a medium that measures file sizes in 512-byte blocks.

Concatenation and padding are not allowed with .lzma files or raw streams. .

KiB Multiply the integer by 1,024 (2^10). Ki , k , kB , K , and KB are accepted as synonyms for KiB .

MiB Multiply the integer by 1,048,576 (2^20). Mi , m , M , and MB are accepted as synonyms for MiB .

GiB Multiply the integer by 1,073,741,824 (2^30). Gi , g , G , and GB are accepted as synonyms for GiB .

The special value max can be used to indicate the maximum integer value supported by the option. .

-z ", " --compress Compress. This is the default operation mode when no operation mode option is specified and no other operation mode is implied from the command name (for example, unxz implies --decompress ).

-d ", " --decompress ", " --uncompress Decompress. The DESCRIPTION section already says this but it's good to repeat it
here because the default behavior is a bit dangerous and new users
in a hurry may skip reading the DESCRIPTION section.
After successful decompression, the source file is removed unless writing to standard output or --keep was specified.

-t ", " --test Test the integrity of compressed files . This option is equivalent to "--decompress --stdout" except that the decompressed data is discarded instead of being written to standard output. No files are created or removed.

-l ", " --list Print information about compressed files . No uncompressed output is produced, and no files are created or removed. In list mode, the program cannot read the compressed data from standard input or from other unseekable sources.

-k ", " --keep Don't delete the input files.

-f ", " --force This option has several effects:

-c ", " --stdout ", " --to-stdout Write the compressed or decompressed data to standard output instead of a file. This implies --keep .

--single-stream Decompress only the first .xz stream, and silently ignore possible remaining input data following the stream. Normally such trailing garbage makes xz display an error.

--no-sparse Disable creation of sparse files. By default, if decompressing into a regular file, xz tries to make the file sparse if the decompressed data contains long sequences of binary zeros. It also works when writing to standard output as long as standard output is connected to a regular file and certain additional conditions are met to make it safe. Creating sparse files may save disk space and speed up the decompression by reducing the amount of disk I/O.

-S .suf, --suffix=.suf When compressing, use .suf as the suffix for the target file instead of .xz or .lzma . If not writing to standard output and the source file already has the suffix .suf , a warning is displayed and the file is skipped.

--files[=file] Read the filenames to process from file ; if file is omitted, filenames are read from standard input. Filenames must be terminated with the newline character. A dash ( - ) is taken as a regular filename; it doesn't mean standard input. If filenames are given also as command line arguments, they are processed before the filenames read from file .

--files0[=file] This is identical to --files[=file] except that each filename must be terminated with the null character. .

-F format, --format=format Specify the file format to compress or decompress:

-C check, --check=check Specify the type of the integrity check. The check is calculated from the uncompressed data and stored in the .xz file. This option has an effect only when compressing into the .xz format; the .lzma format doesn't support integrity checks. The integrity check (if any) is verified when the .xz file is decompressed.

--ignore-check Don't verify the integrity check of the compressed data when decompressing. The CRC32 values in the .xz headers will still be verified normally.

-0 " ... " -9 Select a compression preset level. The default is -6 . If multiple preset levels are specified, the last one takes effect. If a custom filter chain was already specified, setting a compression preset level clears the custom filter chain.

-e ", " --extreme Use a slower variant of the selected compression preset level ( -0 " ... " -9 ) to hopefully get a little bit better compression ratio, but with bad luck this can also make it worse. Decompressor memory usage is not affected, but compressor memory usage increases a little at preset levels -0 " ... " -3 .

--fast

0

--best

These are somewhat misleading aliases for -0 and -9 , respectively. These are provided only for backwards compatibility with LZMA Utils. Avoid using these options.

--block-size= size When compressing to the .xz format, split the input data into blocks of size bytes. The blocks are compressed independently from each other, which helps with multi-threading and makes limited random-access decompression possible. This option is typically used to override the default block size in multi-threaded mode, but this option can be used in single-threaded mode too.

--block-list= items When compressing to the .xz format, start a new block with an optional custom filter chain after the given intervals of uncompressed data.

--flush-timeout= timeout When compressing, if more than timeout milliseconds (a positive integer) has passed since the previous flush and reading more input would block, all the pending input data is flushed from the encoder and made available in the output stream. This can be useful if xz is used to compress data that is streamed over a network. Small timeout values make the data available at the receiving end with a small delay, but large timeout values give better compression ratio.

--no-sync Do not synchronize the target file and its directory to the storage device before removing the source file. This can improve performance if compressing or decompressing many small files. However, if the system crashes soon after the deletion, it is possible that the target file was not written to the storage device but the delete operation was. In that case neither the original source file nor the target file is available.

--memlimit-compress= limit Set a memory usage limit for compression. If this option is specified multiple times, the last one takes effect.

--memlimit-decompress= limit Set a memory usage limit for decompression. This also affects the --list mode. If the operation is not possible without exceeding the limit , xz will display an error and decompressing the file will fail. See --memlimit-compress= limit for possible ways to specify the limit .

--memlimit-mt-decompress= limit Set a memory usage limit for multi-threaded decompression. This can only affect the number of threads; this will never make xz refuse to decompress a file. If limit is too low to allow any multi-threading, the limit is ignored and xz will continue in single-threaded mode. Note that if also --memlimit-decompress is used, it will always apply to both single-threaded and multi-threaded modes, and so the effective limit for multi-threading will never be higher than the limit set with --memlimit-decompress .

-M limit, --memlimit=limit, --memory=limit This is equivalent to specifying --memlimit-compress= limit --memlimit-decompress= limit --memlimit-mt-decompress=limit.

--no-adjust Display an error and exit if the memory usage limit cannot be met without adjusting settings that affect the compressed output. That is, this prevents xz from switching the encoder from multi-threaded mode to single-threaded mode and from reducing the LZMA2 dictionary size. Even when this option is used the number of threads may be reduced to meet the memory usage limit as that won't affect the compressed output.

-T threads, --threads=threads Specify the number of worker threads to use. Setting threads to a special value 0 makes xz use up to as many threads as the processor(s) on the system support. The actual number of threads can be fewer than threads if the input file is not big enough for threading with the given settings or if using more threads would exceed the memory usage limit.

A filter chain is comparable to piping on the command line. When compressing, the uncompressed input goes to the first filter, whose output goes to the next filter (if any). The output of the last filter gets written to the compressed file. The maximum number of filters in the chain is four, but typically a filter chain has only one or two filters.

Many filters have limitations on where they can be in the filter chain: some filters can work only as the last filter in the chain, some only as a non-last filter, and some work in any position in the chain. Depending on the filter, this limitation is either inherent to the filter design or exists to prevent security issues.

A custom filter chain can be specified in two different ways. The options --filters= filters and --filters1= filters ...\& --filters9= filters allow specifying an entire filter chain in one option using the liblzma filter string syntax. Alternatively, a filter chain can be specified by using one or more individual filter options in the order they are wanted in the filter chain. That is, the order of the individual filter options is significant! When decoding raw streams ( --format=raw ), the filter chain must be specified in the same order as it was specified when compressing. Any individual filter or preset options specified before the full chain option (--filters=filters) will be forgotten. Individual filters specified after the full chain option will reset the filter chain.

Both the full and individual filter options take filter-specific options as a comma-separated list. Extra commas in options are ignored. Every option has a default value, so specify those you want to change.

To see the whole filter chain and options , use "xz -vv" (that is, use --verbose twice). This works also for viewing the filter chain options used by presets.

--filters= filters Specify the full filter chain or a preset in a single option. Each filter can be separated by spaces or two dashes ( -- ). filters may need to be quoted on the shell command line so it is parsed as a single option. To denote options , use : or = . A preset can be prefixed with a - and followed with zero or more flags. The only supported flag is e to apply the same options as --extreme .

--filters1=filters ... --filters9=filters Specify up to nine additional filter chains that can be used with --block-list .

--filters-help Display a help message describing how to specify presets and custom filter chains in the --filters and --filters1= filters ...\& --filters9= filters options, and exit successfully.

--lzma1[=options]

0

--lzma2[=options]

Add LZMA1 or LZMA2 filter to the filter chain. These filters can be used only as the last filter in the chain.

--x86[=options]

0

--arm[=options]

--armthumb[=options]

--arm64[=options]

--powerpc[=options]

--ia64[=options]

--sparc[=options]

--riscv[=options]

Add a branch/call/jump (BCJ) filter to the filter chain. These filters can be used only as a non-last filter in the filter chain.

--delta[=options] Add the Delta filter to the filter chain. The Delta filter can be only used as a non-last filter in the filter chain.

-q ", " --quiet Suppress warnings and notices. Specify this twice to suppress errors too. This option has no effect on the exit status. That is, even if a warning was suppressed, the exit status to indicate a warning is still used.

-v ", " --verbose Be verbose. If standard error is connected to a terminal, xz will display a progress indicator. Specifying --verbose twice will give even more verbose output.

-Q ", " --no-warn Don't set the exit status to 2 even if a condition worth a warning was detected. This option doesn't affect the verbosity level, thus both --quiet and --no-warn have to be used to not display warnings and to not alter the exit status.

--robot Print messages in a machine-parsable format. This is intended to ease writing frontends that want to use xz instead of liblzma, which may be the case with various scripts. The output with this option enabled is meant to be stable across xz releases. See the section "ROBOT MODE" for details.

--info-memory Display, in human-readable format, how much physical memory (RAM) and how many processor threads xz thinks the system has and the memory usage limits for compression and decompression, and exit successfully.

-h ", " --help Display a help message describing the most commonly used options, and exit successfully.

-H ", " --long-help Display a help message describing all features of xz , and exit successfully

-V ", " --version Display the version number of xz and liblzma in human readable format. To get machine-parsable output, specify --robot before --version . .

TRANSLATORS: The bold strings B<name>, B<file>, B<stream>, B<block>,
B<summary>, and B<totals> are produced by the xz tool for scripts to
parse, thus the untranslated strings must be included in the translated
man page. It may be useful to provide a translated string in parenthesis
without bold, for example: "B<name> (nimi)"
name This is always the first line when starting to list a file. The second column on the line is the filename.

file This line contains overall information about the .xz file. This line is always printed after the name line.

stream This line type is used only when --verbose was specified. There are as many stream lines as there are streams in the .xz file.

block This line type is used only when --verbose was specified. There are as many block lines as there are blocks in the .xz file. The block lines are shown after all the stream lines; different line types are not interleaved.

summary This line type is used only when --verbose was specified twice. This line is printed after all block lines. Like the file line, the summary line contains overall information about the .xz file.

totals This line is always the very last line of the list output. It shows the total counts and sizes.

The columns of the file lines:

0

The columns of the stream lines:

0

The columns of the block lines:

0

If --verbose was specified twice, additional columns are included on the block lines. These are not displayed with a single --verbose , because getting this information requires many seeks and can thus be slow:

0

The columns of the summary lines:

0

The columns of the totals line:

0

If --verbose was specified twice, additional columns are included on the totals line:

0

Future versions may add new line types and new columns can be added to the existing line types, but the existing columns won't be changed. .

filter:option=<value>,option=<value>...

filter Name of the filter

option Name of a filter specific option

value Numeric value ranges appear as <min-max>. String value choices are shown within "< >" and separated by a | character.

Each filter is printed on its own line. .

In the future, the output of "xz --robot --info-memory" may have more columns, but never more than a single line. .

TRANSLATORS: Don't translate the uppercase XZ_VERSION or LIBLZMA_VERSION.
XZ_VERSION= XYYYZZZS

LIBLZMA_VERSION= XYYYZZZS

X Major version.

YYY Minor version. Even numbers are stable. Odd numbers are alpha or beta versions.

ZZZ Patch level for stable releases or just a counter for development releases.

S Stability. 0 is alpha, 1 is beta, and 2 is stable. S should be always 2 when YYY is even.

XYYYZZZS are the same on both lines if xz and liblzma are from the same XZ Utils release.

Examples: 4.999.9beta is 49990091 and 5.0.0 is 50000002 . .

0 All is good.

1 An error occurred.

2 Something worth a warning occurred, but no actual errors occurred.

Notices (not warnings or errors) printed on standard error don't affect the exit status. .

Warning: By setting these environment variables, one is effectively modifying programs and scripts that run xz . Most of the time it is safe to set memory usage limits, number of threads, and compression options via the environment variables. However, some options can break scripts. An obvious example is --help which makes xz show the help text instead of compressing or decompressing a file. More subtle examples are --quiet and --verbose . In many cases it works well to enable the progress indicator using --verbose , but in some situations the extra messages create problems. The verbosity level also affects the behavior of --list .

XZ_DEFAULTS User-specific or system-wide default options. Typically this is set in a shell initialization script to enable xz 's memory usage limiter by default or set the default number of threads. Excluding shell initialization scripts and similar special cases, scripts should never set or unset XZ_DEFAULTS .

XZ_OPT This is for passing options to xz when it is not possible to set the options directly on the xz command line. This is the case when xz is run by a script or tool, for example, GNU tar (1):

XZ_OPT=-2v tar caf foo.tar.xz foo

XZ_OPT=${XZ_OPT-"-7e"}
export XZ_OPT

The dictionary size differences affect the compressor memory usage too, but there are some other differences between LZMA Utils and XZ Utils, which make the difference even bigger:

The default preset level in LZMA Utils is -7 while in XZ Utils it is -6 , so both use an 8 MiB dictionary by default. .

xz supports decompressing .lzma files with or without end-of-payload marker, but all .lzma files created by xz will use end-of-payload marker and have uncompressed size marked as unknown in the .lzma header. This may be a problem in some uncommon situations. For example, a .lzma decompressor in an embedded device might work only with files that have known uncompressed size. If you hit this problem, you need to use LZMA Utils or LZMA SDK to create .lzma files with known uncompressed size. .

The implementation of the LZMA1 filter in liblzma requires that the sum of lc and lp must not exceed 4. Thus, .lzma files, which exceed this limitation, cannot be decompressed with xz .

LZMA Utils creates only .lzma files which have a dictionary size of "2^" n (a power of 2) but accepts files with any dictionary size. liblzma accepts only .lzma files which have a dictionary size of "2^" n or "2^" n " + 2^(" n "-1)." This is to decrease false positives when detecting .lzma files.

These limitations shouldn't be a problem in practice, since practically all .lzma files have been compressed with settings that liblzma will accept. .

If there is data left after the first .lzma stream, xz considers the file to be corrupt unless --single-stream was used. This may break obscure scripts which have assumed that trailing garbage is ignored. .

The above means that once --rsyncable has been implemented, the resulting files won't necessarily be rsyncable unless both old and new files have been compressed with the same xz version. This problem can be fixed if a part of the encoder implementation is frozen to keep rsyncable output stable across xz versions. .

Outside embedded systems, all .xz format decompressors support all the check types, or at least are able to decompress the file without verifying the integrity check if the particular check is not supported.

XZ Embedded supports BCJ filters, but only with the default start offset. .

xz foo

Decompress bar.xz into bar and don't remove bar.xz even if decompression is successful:

xz -dk bar.xz

Create baz.tar.xz with the preset -4e ( "-4 --extreme" ), which is slower than the default -6 , but needs less memory for compression and decompression (48 MiB and 5 MiB, respectively):

tar cf - baz | xz -4e > baz.tar.xz

A mix of compressed and uncompressed files can be decompressed to standard output with a single command:

xz -dcf a.txt b.txt.xz c.txt d.txt.lzma > abcd.txt

find . -type f \e! -name '*.xz' -print0 \e
 | xargs -0r -P4 -n16 xz -T1

The -P option to xargs (1) sets the number of parallel xz processes. The best value for the -n option depends on how many files there are to be compressed. If there are only a couple of files, the value should probably be 1; with tens of thousands of files, 100 or even more may be appropriate to reduce the number of xz processes that xargs (1) will eventually create.

The option -T1 for xz is there to force it to single-threaded mode, because xargs (1) is used to control the amount of parallelization. .

xz --robot --list *.xz | awk '/^totals/{print $5-$4}'

A script may want to know that it is using new enough xz . The following sh (1) script checks that the version number of the xz tool is at least 5.0.0. This method is compatible with old beta versions, which didn't support the --robot option:

if ! eval "$(xz --robot --version 2> /dev/null)" ||
 [ "$XZ_VERSION" -lt 50000002 ]; then
 echo "Your xz is too old."
fi
unset XZ_VERSION LIBLZMA_VERSION

Set a memory usage limit for decompression using XZ_OPT , but if a limit has already been set, don't increase it:

NEWLIM=$((123 << 20))  # 123 MiB
OLDLIM=$(xz --robot --info-memory | cut -f3)
if [ $OLDLIM -eq 0 -o $OLDLIM -gt $NEWLIM ]; then
 XZ_OPT="$XZ_OPT --memlimit-decompress=$NEWLIM"
 export XZ_OPT
fi

The CompCPU columns of the tables from the descriptions of the options "-0" " ... " "-9" and --extreme are useful when customizing LZMA2 presets. Here are the relevant parts collected from those two tables:

If you know that a file requires somewhat big dictionary (for example, 32 MiB) to compress well, but you want to compress it quicker than "xz -8" would do, a preset with a low CompCPU value (for example, 1) can be modified to use a bigger dictionary:

xz --lzma2=preset=1,dict=32MiB foo.tar

With certain files, the above command may be faster than "xz -6" while compressing significantly better. However, it must be emphasized that only some files benefit from a big dictionary while keeping the CompCPU value low. The most obvious situation, where a big dictionary can help a lot, is an archive containing very similar files of at least a few megabytes each. The dictionary size has to be significantly bigger than any individual file to allow LZMA2 to take full advantage of the similarities between consecutive files.

If very high compressor and decompressor memory usage is fine, and the file being compressed is at least several hundred megabytes, it may be useful to use an even bigger dictionary than the 64 MiB that "xz -9" would use:

xz -vv --lzma2=dict=192MiB big_foo.tar

Using -vv ( "--verbose --verbose" ) like in the above example can be useful to see the memory requirements of the compressor and decompressor. Remember that using a dictionary bigger than the size of the uncompressed file is waste of memory, so the above command isn't useful for small files.

Sometimes the compression time doesn't matter, but the decompressor memory usage has to be kept low, for example, to make it possible to decompress the file on an embedded system. The following command uses -6e ( "-6 --extreme" ) as a base and sets the dictionary to only 64 KiB. The resulting file can be decompressed with XZ Embedded (that's why there is --check=crc32 ) using about 100 KiB of memory.

xz --check=crc32 --lzma2=preset=6e,dict=64KiB foo

If you want to squeeze out as many bytes as possible, adjusting the number of literal context bits ( lc ) and number of position bits ( pb ) can sometimes help. Adjusting the number of literal position bits ( lp ) might help too, but usually lc and pb are more important. For example, a source code archive contains mostly US-ASCII text, so something like the following might give slightly (like 0.1 %) smaller file than "xz -6e" (try also without lc=4 ):

xz --lzma2=preset=6e,pb=0,lc=4 source_code.tar

Using another filter together with LZMA2 can improve compression with certain file types. For example, to compress a x86-32 or x86-64 shared library using the x86 BCJ filter:

xz --x86 --lzma2 libfoo.so

Note that the order of the filter options is significant. If --x86 is specified after --lzma2 , xz will give an error, because there cannot be any filter after LZMA2, and also because the x86 BCJ filter cannot be used as the last filter in the chain.

The Delta filter together with LZMA2 can give good results with bitmap images. It should usually beat PNG, which has a few more advanced filters than simple delta but uses Deflate for the actual compression.

The image has to be saved in uncompressed format, for example, as uncompressed TIFF. The distance parameter of the Delta filter is set to match the number of bytes per pixel in the image. For example, 24-bit RGB bitmap needs dist=3 , and it is also good to pass pb=0 to LZMA2 to accommodate the three-byte alignment:

xz --delta=dist=3 --lzma2=pb=0 foo.tiff

If multiple images have been put into a single archive (for example, .tar ), the Delta filter will work on that too as long as all images have the same number of bytes per pixel. .

XZ Utils: <https://tukaani.org/xz/>

XZ Embedded: <https://tukaani.org/xz/embedded.html>

LZMA SDK: <https://7-zip.org/sdk.html>