1XZ(1) XZ Utils XZ(1)
2
6 xz, unxz, xzcat, lzma, unlzma, lzcat - Compress or decompress .xz and
7 .lzma files
8
10 xz [option]... [file]...
11 unxz is equivalent to xz --decompress.
13 xzcat is equivalent to xz --decompress --stdout.
14 lzma is equivalent to xz --format=lzma.
15 unlzma is equivalent to xz --format=lzma --decompress.
16 lzcat is equivalent to xz --format=lzma --decompress --stdout.
17 When writing scripts that need to decompress files, it is recommended
19 to always use the name xz with appropriate arguments (xz -d or xz -dc)
20 instead of the names unxz and xzcat.
21
23 xz is a general-purpose data compression tool with command line syntax
24 similar to gzip(1) and bzip2(1). The native file format is the .xz
25 format, but also the legacy .lzma format and raw compressed streams
26 with no container format headers are supported.
27 xz compresses or decompresses each file according to the selected oper‐
29 ation mode. If no files are given or file is -, xz reads from standard
30 input and writes the processed data to standard output. xz will refuse
31 (display an error and skip the file) to write compressed data to stan‐
32 dard output if it is a terminal. Similarly, xz will refuse to read com‐
33 pressed data from standard input if it is a terminal.
34 Unless --stdout is specified, files other than - are written to a new
36 file whose name is derived from the source file name:
37 · When compressing, the suffix of the target file format (.xz or
39 .lzma) is appended to the source filename to get the target file‐
40 name.
41 · When decompressing, the .xz or .lzma suffix is removed from the
43 filename to get the target filename. xz also recognizes the suf‐
44 fixes .txz and .tlz, and replaces them with the .tar suffix.
45 If the target file already exists, an error is displayed and the file
47 is skipped.
48 Unless writing to standard output, xz will display a warning and skip
50 the file if any of the following applies:
51 · File is not a regular file. Symbolic links are not followed, thus
53 they are not considered to be regular files.
54 · File has more than one hard link.
56 · File has setuid, setgid, or sticky bit set.
58 · The operation mode is set to compress, and the file already has a
60 suffix of the target file format (.xz or .txz when compressing to
61 the .xz format, and .lzma or .tlz when compressing to the .lzma for‐
62 mat).
63 · The operation mode is set to decompress, and the file doesn't have a
65 suffix of any of the supported file formats (.xz, .txz, .lzma, or
66 .tlz).
67 After successfully compressing or decompressing the file, xz copies the
69 owner, group, permissions, access time, and modification time from the
70 source file to the target file. If copying the group fails, the permis‐
71 sions are modified so that the target file doesn't become accessible to
72 users who didn't have permission to access the source file. xz doesn't
73 support copying other metadata like access control lists or extended
74 attributes yet.
75 Once the target file has been successfully closed, the source file is
77 removed unless --keep was specified. The source file is never removed
78 if the output is written to standard output.
79 Sending SIGINFO or SIGUSR1 to the xz process makes it print progress
81 information to standard error. This has only limited use since when
82 standard error is a terminal, using --verbose will display an automati‐
83 cally updating progress indicator.
84 Memory usage
86 The memory usage of xz varies from a few hundred kilobytes to several
87 gigabytes depending on the compression settings. The settings used when
88 compressing a file affect also the memory usage of the decompressor.
89 Typically the decompressor needs only 5 % to 20 % of the amount of RAM
90 that the compressor needed when creating the file. Still, the worst-
91 case memory usage of the decompressor is several gigabytes.
92 To prevent uncomfortable surprises caused by huge memory usage, xz has
94 a built-in memory usage limiter. While some operating systems provide
95 ways to limit the memory usage of processes, relying on it wasn't
96 deemed to be flexible enough. The default limit depends on the total
97 amount of physical RAM:
98 · If 40 % of RAM is at least 80 MiB, 40 % of RAM is used as the limit.
100 · If 80 % of RAM is over 80 MiB, 80 MiB is used as the limit.
102 · Otherwise 80 % of RAM is used as the limit.
104 When compressing, if the selected compression settings exceed the mem‐
106 ory usage limit, the settings are automatically adjusted downwards and
107 a notice about this is displayed. As an exception, if the memory usage
108 limit is exceeded when compressing with --format=raw, an error is dis‐
109 played and xz will exit with exit status 1.
110 If source file cannot be decompressed without exceeding the memory
112 usage limit, an error message is displayed and the file is skipped.
113 Note that compressed files may contain many blocks, which may have been
114 compressed with different settings. Typically all blocks will have
115 roughly the same memory requirements, but it is possible that a block
116 later in the file will exceed the memory usage limit, and an error
117 about too low memory usage limit gets displayed after some data has
118 already been decompressed.
119 The absolute value of the active memory usage limit can be seen with
121 --info-memory or near the bottom of the output of --long-help. The
122 default limit can be overridden with --memory=limit.
123
125 Integer suffixes and special values
126 In most places where an integer argument is expected, an optional suf‐
127 fix is supported to easily indicate large integers. There must be no
128 space between the integer and the suffix.
129 KiB The integer is multiplied by 1,024 (2^10). Also Ki, k, kB, K,
131 and KB are accepted as synonyms for KiB.
132 MiB The integer is multiplied by 1,048,576 (2^20). Also Mi, m, M,
134 and MB are accepted as synonyms for MiB.
135 GiB The integer is multiplied by 1,073,741,824 (2^30). Also Gi, g,
137 G, and GB are accepted as synonyms for GiB.
138 A special value max can be used to indicate the maximum integer value
140 supported by the option.
141 Operation mode
143 If multiple operation mode options are given, the last one takes
144 effect.
145 -z, --compress
147 Compress. This is the default operation mode when no operation
148 mode option is specified, and no other operation mode is implied
149 from the command name (for example, unxz implies --decompress).
150 -d, --decompress, --uncompress
152 Decompress.
153 -t, --test
155 Test the integrity of compressed files. No files are created or
156 removed. This option is equivalent to --decompress --stdout
157 except that the decompressed data is discarded instead of being
158 written to standard output.
159 -l, --list
161 View information about the compressed files. No uncompressed
162 output is produced, and no files are created or removed. In list
163 mode, the program cannot read the compressed data from standard
164 input or from other unseekable sources.
165 This feature has not been implemented yet.
167 Operation modifiers
169 -k, --keep
170 Keep (don't delete) the input files.
171 -f, --force
173 This option has several effects:
174 · If the target file already exists, delete it before compress‐
176 ing or decompressing.
177 · Compress or decompress even if the input is a symbolic link
179 to a regular file, has more than one hard link, or has
180 setuid, setgid, or sticky bit set. The setuid, setgid, and
181 sticky bits are not copied to the target file.
182 · If combined with --decompress --stdout and xz doesn't recog‐
184 nize the type of the source file, xz will copy the source
185 file as is to standard output. This allows using xzcat
186 --force like cat(1) for files that have not been compressed
187 with xz. Note that in future, xz might support new com‐
188 pressed file formats, which may make xz decompress more types
189 of files instead of copying them as is to standard output.
190 --format=format can be used to restrict xz to decompress only
191 a single file format.
192 -c, --stdout, --to-stdout
194 Write the compressed or decompressed data to standard output
195 instead of a file. This implies --keep.
196 --no-sparse
198 Disable creation of sparse files. By default, if decompressing
199 into a regular file, xz tries to make the file sparse if the
200 decompressed data contains long sequences of binary zeros. It
201 works also when writing to standard output as long as standard
202 output is connected to a regular file, and certain additional
203 conditions are met to make it safe. Creating sparse files may
204 save disk space and speed up the decompression by reducing the
205 amount of disk I/O.
206 -S .suf, --suffix=.suf
208 When compressing, use .suf as the suffix for the target file
209 instead of .xz or .lzma. If not writing to standard output and
210 the source file already has the suffix .suf, a warning is dis‐
211 played and the file is skipped.
212 When decompressing, recognize also files with the suffix .suf in
214 addition to files with the .xz, .txz, .lzma, or .tlz suffix. If
215 the source file has the suffix .suf, the suffix is removed to
216 get the target filename.
217 When compressing or decompressing raw streams (--format=raw),
219 the suffix must always be specified unless writing to standard
220 output, because there is no default suffix for raw streams.
221 --files[=file]
223 Read the filenames to process from file; if file is omitted,
224 filenames are read from standard input. Filenames must be termi‐
225 nated with the newline character. A dash (-) is taken as a regu‐
226 lar filename; it doesn't mean standard input. If filenames are
227 given also as command line arguments, they are processed before
228 the filenames read from file.
229 --files0[=file]
231 This is identical to --files[=file] except that the filenames
232 must be terminated with the null character.
233 Basic file format and compression options
235 -F format, --format=format
236 Specify the file format to compress or decompress:
237 · auto: This is the default. When compressing, auto is equiva‐
239 lent to xz. When decompressing, the format of the input file
240 is automatically detected. Note that raw streams (created
241 with --format=raw) cannot be auto-detected.
242 · xz: Compress to the .xz file format, or accept only .xz files
244 when decompressing.
245 · lzma or alone: Compress to the legacy .lzma file format, or
247 accept only .lzma files when decompressing. The alternative
248 name alone is provided for backwards compatibility with LZMA
249 Utils.
250 · raw: Compress or uncompress a raw stream (no headers). This
252 is meant for advanced users only. To decode raw streams, you
253 need to set not only --format=raw but also specify the filter
254 chain, which would normally be stored in the container format
255 headers.
256 -C check, --check=check
258 Specify the type of the integrity check, which is calculated
259 from the uncompressed data. This option has an effect only when
260 compressing into the .xz format; the .lzma format doesn't sup‐
261 port integrity checks. The integrity check (if any) is verified
262 when the .xz file is decompressed.
263 Supported check types:
265 · none: Don't calculate an integrity check at all. This is usu‐
267 ally a bad idea. This can be useful when integrity of the
268 data is verified by other means anyway.
269 · crc32: Calculate CRC32 using the polynomial from IEEE-802.3
271 (Ethernet).
272 · crc64: Calculate CRC64 using the polynomial from ECMA-182.
274 This is the default, since it is slightly better than CRC32
275 at detecting damaged files and the speed difference is negli‐
276 gible.
277 · sha256: Calculate SHA-256. This is somewhat slower than CRC32
279 and CRC64.
280 Integrity of the .xz headers is always verified with CRC32. It
282 is not possible to change or disable it.
283 -0 ... -9
285 Select compression preset. If a preset level is specified multi‐
286 ple times, the last one takes effect.
287 The compression preset levels can be categorised roughly into
289 three categories:
290 -0 ... -2
292 Fast presets with relatively low memory usage. -1 and -2
293 should give compression speed and ratios comparable to
294 bzip2 -1 and bzip2 -9, respectively. Currently -0 is not
295 very good (not much faster than -1 but much worse com‐
296 pression). In future, -0 may be indicate some fast algo‐
297 rithm instead of LZMA2.
298 -3 ... -5
300 Good compression ratio with low to medium memory usage.
301 These are significantly slower than levels 0-2.
302 -6 ... -9
304 Excellent compression with medium to high memory usage.
305 These are also slower than the lower preset levels. The
306 default is -6. Unless you want to maximize the compres‐
307 sion ratio, you probably don't want a higher preset level
308 than -7 due to speed and memory usage.
309 The exact compression settings (filter chain) used by each pre‐
311 set may vary between xz versions. The settings may also vary
312 between files being compressed, if xz determines that modified
313 settings will probably give better compression ratio without
314 significantly affecting compression time or memory usage.
315 Because the settings may vary, the memory usage may vary too.
317 The following table lists the maximum memory usage of each pre‐
318 set level, which won't be exceeded even in future versions of
319 xz.
320 FIXME: The table below is just a rough idea.
322 Preset Compression Decompression
324 -0 6 MiB 1 MiB
325 -1 6 MiB 1 MiB
326 -2 10 MiB 1 MiB
327 -3 20 MiB 2 MiB
328 -4 30 MiB 3 MiB
329 -5 60 MiB 6 MiB
330 -6 100 MiB 10 MiB
331 -7 200 MiB 20 MiB
332 -8 400 MiB 40 MiB
333 -9 800 MiB 80 MiB
334 When compressing, xz automatically adjusts the compression set‐
336 tings downwards if the memory usage limit would be exceeded, so
337 it is safe to specify a high preset level even on systems that
338 don't have lots of RAM.
339 --fast and --best
341 These are somewhat misleading aliases for -0 and -9, respec‐
342 tively. These are provided only for backwards compatibility
343 with LZMA Utils. Avoid using these options.
344 Especially the name of --best is misleading, because the defini‐
346 tion of best depends on the input data, and that usually people
347 don't want the very best compression ratio anyway, because it
348 would be very slow.
349 -e, --extreme
351 Modify the compression preset (-0 ... -9) so that a little bit
352 better compression ratio can be achieved without increasing mem‐
353 ory usage of the compressor or decompressor (exception: compres‐
354 sor memory usage may increase a little with presets -0 ... -2).
355 The downside is that the compression time will increase dramati‐
356 cally (it can easily double).
357 -M limit, --memory=limit
359 Set the memory usage limit. If this option is specified multiple
360 times, the last one takes effect. The limit can be specified in
361 multiple ways:
362 · The limit can be an absolute value in bytes. Using an integer
364 suffix like MiB can be useful. Example: --memory=80MiB
365 · The limit can be specified as a percentage of physical RAM.
367 Example: --memory=70%
368 · The limit can be reset back to its default value by setting
370 it to 0. See the section Memory usage for how the default
371 limit is defined.
372 · The memory usage limiting can be effectively disabled by set‐
374 ting limit to max. This isn't recommended. It's usually bet‐
375 ter to use, for example, --memory=90%.
376 The current limit can be seen near the bottom of the output of
378 the --long-help option.
379 -T threads, --threads=threads
381 Specify the maximum number of worker threads to use. The default
382 is the number of available CPU cores. You can see the current
383 value of threads near the end of the output of the --long-help
384 option.
385 The actual number of worker threads can be less than threads if
387 using more threads would exceed the memory usage limit. In
388 addition to CPU-intensive worker threads, xz may use a few aux‐
389 iliary threads, which don't use a lot of CPU time.
390 Multithreaded compression and decompression are not implemented
392 yet, so this option has no effect for now.
393 Custom compressor filter chains
395 A custom filter chain allows specifying the compression settings in
396 detail instead of relying on the settings associated to the preset lev‐
397 els. When a custom filter chain is specified, the compression preset
398 level options (-0 ... -9 and --extreme) are silently ignored.
399 A filter chain is comparable to piping on the UN*X command line. When
401 compressing, the uncompressed input goes to the first filter, whose
402 output goes to the next filter (if any). The output of the last filter
403 gets written to the compressed file. The maximum number of filters in
404 the chain is four, but typically a filter chain has only one or two
405 filters.
406 Many filters have limitations where they can be in the filter chain:
408 some filters can work only as the last filter in the chain, some only
409 as a non-last filter, and some work in any position in the chain.
410 Depending on the filter, this limitation is either inherent to the fil‐
411 ter design or exists to prevent security issues.
412 A custom filter chain is specified by using one or more filter options
414 in the order they are wanted in the filter chain. That is, the order of
415 filter options is significant! When decoding raw streams (--for‐
416 mat=raw), the filter chain is specified in the same order as it was
417 specified when compressing.
418 Filters take filter-specific options as a comma-separated list. Extra
420 commas in options are ignored. Every option has a default value, so you
421 need to specify only those you want to change.
422 --lzma1[=options], --lzma2[=options]
424 Add LZMA1 or LZMA2 filter to the filter chain. These filter can
425 be used only as the last filter in the chain.
426 LZMA1 is a legacy filter, which is supported almost solely due
428 to the legacy .lzma file format, which supports only LZMA1.
429 LZMA2 is an updated version of LZMA1 to fix some practical
430 issues of LZMA1. The .xz format uses LZMA2, and doesn't support
431 LZMA1 at all. Compression speed and ratios of LZMA1 and LZMA2
432 are practically the same.
433 LZMA1 and LZMA2 share the same set of options:
435 preset=preset
437 Reset all LZMA1 or LZMA2 options to preset. Preset con‐
438 sist of an integer, which may be followed by single-let‐
439 ter preset modifiers. The integer can be from 0 to 9,
440 matching the command line options -0 ... -9. The only
441 supported modifier is currently e, which matches
442 --extreme.
443 The default preset is 6, from which the default values
445 for the rest of the LZMA1 or LZMA2 options are taken.
446 dict=size
448 Dictionary (history buffer) size indicates how many bytes
449 of the recently processed uncompressed data is kept in
450 memory. One method to reduce size of the uncompressed
451 data is to store distance-length pairs, which indicate
452 what data to repeat from the dictionary buffer. The big‐
453 ger the dictionary, the better the compression ratio usu‐
454 ally is, but dictionaries bigger than the uncompressed
455 data are waste of RAM.
456 Typical dictionary size is from 64 KiB to 64 MiB. The
458 minimum is 4 KiB. The maximum for compression is cur‐
459 rently 1.5 GiB. The decompressor already supports dictio‐
460 naries up to one byte less than 4 GiB, which is the maxi‐
461 mum for LZMA1 and LZMA2 stream formats.
462 Dictionary size has the biggest effect on compression
464 ratio. Dictionary size and match finder together deter‐
465 mine the memory usage of the LZMA1 or LZMA2 encoder. The
466 same dictionary size is required for decompressing that
467 was used when compressing, thus the memory usage of the
468 decoder is determined by the dictionary size used when
469 compressing.
470 lc=lc Specify the number of literal context bits. The minimum
472 is 0 and the maximum is 4; the default is 3. In addi‐
473 tion, the sum of lc and lp must not exceed 4.
474 lp=lp Specify the number of literal position bits. The minimum
476 is 0 and the maximum is 4; the default is 0.
477 pb=pb Specify the number of position bits. The minimum is 0 and
479 the maximum is 4; the default is 2.
480 mode=mode
482 Compression mode specifies the function used to analyze
483 the data produced by the match finder. Supported modes
484 are fast and normal. The default is fast for presets 0-2
485 and normal for presets 3-9.
486 mf=mf Match finder has a major effect on encoder speed, memory
488 usage, and compression ratio. Usually Hash Chain match
489 finders are faster than Binary Tree match finders. Hash
490 Chains are usually used together with mode=fast and
491 Binary Trees with mode=normal. The memory usage formulas
492 are only rough estimates, which are closest to reality
493 when dict is a power of two.
494 hc3 Hash Chain with 2- and 3-byte hashing
496 Minimum value for nice: 3
497 Memory usage: dict * 7.5 (if dict <= 16 MiB);
498 dict * 5.5 + 64 MiB (if dict > 16 MiB)
499 hc4 Hash Chain with 2-, 3-, and 4-byte hashing
501 Minimum value for nice: 4
502 Memory usage: dict * 7.5
503 bt2 Binary Tree with 2-byte hashing
505 Minimum value for nice: 2
506 Memory usage: dict * 9.5
507 bt3 Binary Tree with 2- and 3-byte hashing
509 Minimum value for nice: 3
510 Memory usage: dict * 11.5 (if dict <= 16 MiB);
511 dict * 9.5 + 64 MiB (if dict > 16 MiB)
512 bt4 Binary Tree with 2-, 3-, and 4-byte hashing
514 Minimum value for nice: 4
515 Memory usage: dict * 11.5
516 nice=nice
518 Specify what is considered to be a nice length for a
519 match. Once a match of at least nice bytes is found, the
520 algorithm stops looking for possibly better matches.
521 nice can be 2-273 bytes. Higher values tend to give bet‐
523 ter compression ratio at expense of speed. The default
524 depends on the preset level.
525 depth=depth
527 Specify the maximum search depth in the match finder. The
528 default is the special value 0, which makes the compres‐
529 sor determine a reasonable depth from mf and nice.
530 Using very high values for depth can make the encoder
532 extremely slow with carefully crafted files. Avoid set‐
533 ting the depth over 1000 unless you are prepared to
534 interrupt the compression in case it is taking too long.
535 When decoding raw streams (--format=raw), LZMA2 needs only the
537 value of dict. LZMA1 needs also lc, lp, and pb.
538 --x86[=options]
540 --powerpc[=options]
542 --ia64[=options]
544 --arm[=options]
546 --armthumb[=options]
548 --sparc[=options]
550 Add a branch/call/jump (BCJ) filter to the filter chain. These
551 filters can be used only as non-last filter in the filter chain.
552 A BCJ filter converts relative addresses in the machine code to
554 their absolute counterparts. This doesn't change the size of the
555 data, but it increases redundancy, which allows e.g. LZMA2 to
556 get better compression ratio.
557 The BCJ filters are always reversible, so using a BCJ filter for
559 wrong type of data doesn't cause any data loss. However, apply‐
560 ing a BCJ filter for wrong type of data is a bad idea, because
561 it tends to make the compression ratio worse.
562 Different instruction sets have have different alignment:
564 Filter Alignment Notes
566 x86 1 32-bit and 64-bit x86
567 PowerPC 4 Big endian only
568 ARM 4 Little endian only
569 ARM-Thumb 2 Little endian only
570 IA-64 16 Big or little endian
571 SPARC 4 Big or little endian
572 Since the BCJ-filtered data is usually compressed with LZMA2,
574 the compression ratio may be improved slightly if the LZMA2
575 options are set to match the alignment of the selected BCJ fil‐
576 ter. For example, with the IA-64 filter, it's good to set pb=4
577 with LZMA2 (2^4=16). The x86 filter is an exception; it's usu‐
578 ally good to stick to LZMA2's default four-byte alignment when
579 compressing x86 executables.
580 All BCJ filters support the same options:
582 start=offset
584 Specify the start offset that is used when converting
585 between relative and absolute addresses. The offset must
586 be a multiple of the alignment of the filter (see the ta‐
587 ble above). The default is zero. In practice, the
588 default is good; specifying a custom offset is almost
589 never useful.
590 Specifying a non-zero start offset is probably useful
592 only if the executable has multiple sections, and there
593 are many cross-section jumps or calls. Applying a BCJ
594 filter separately for each section with proper start off‐
595 set and then compressing the result as a single chunk may
596 give some improvement in compression ratio compared to
597 applying the BCJ filter with the default offset for the
598 whole executable.
599 --delta[=options]
601 Add Delta filter to the filter chain. The Delta filter can be
602 used only as non-last filter in the filter chain.
603 Currently only simple byte-wise delta calculation is supported.
605 It can be useful when compressing e.g. uncompressed bitmap
606 images or uncompressed PCM audio. However, special purpose algo‐
607 rithms may give significantly better results than Delta + LZMA2.
608 This is true especially with audio, which compresses faster and
609 better e.g. with FLAC.
610 Supported options:
612 dist=distance
614 Specify the distance of the delta calculation as bytes.
615 distance must be 1-256. The default is 1.
616 For example, with dist=2 and eight-byte input A1 B1 A2 B3
618 A3 B5 A4 B7, the output will be A1 B1 01 02 01 02 01 02.
619 Other options
621 -q, --quiet
622 Suppress warnings and notices. Specify this twice to suppress
623 errors too. This option has no effect on the exit status. That
624 is, even if a warning was suppressed, the exit status to indi‐
625 cate a warning is still used.
626 -v, --verbose
628 Be verbose. If standard error is connected to a terminal, xz
629 will display a progress indicator. Specifying --verbose twice
630 will give even more verbose output (useful mostly for debug‐
631 ging).
632 The progress indicator shows the following information:
634 · Completion percentage is shown if the size of the input file
636 is known. That is, percentage cannot be shown in pipes.
637 · Amount of compressed data produced (compressing) or consumed
639 (decompressing).
640 · Amount of uncompressed data consumed (compressing) or pro‐
642 duced (decompressing).
643 · Compression ratio, which is calculated by dividing the amount
645 of compressed data processed so far by the amount of uncom‐
646 pressed data processed so far.
647 · Compression or decompression speed. This is measured as the
649 amount of uncompressed data consumed (compression) or pro‐
650 duced (decompression) per second. It is shown once a few sec‐
651 onds have passed since xz started processing the file.
652 · Elapsed time or estimated time remaining. Elapsed time is
654 displayed in the format M:SS or H:MM:SS. The estimated
655 remaining time is displayed in a less precise format which
656 never has colons, for example, 2 min 30 s. The estimate can
657 be shown only when the size of the input file is known and a
658 couple of seconds have already passed since xz started pro‐
659 cessing the file.
660 When standard error is not a terminal, --verbose will make xz
662 print the filename, compressed size, uncompressed size, compres‐
663 sion ratio, speed, and elapsed time on a single line to standard
664 error after compressing or decompressing the file. If operating
665 took at least a few seconds, also the speed and elapsed time are
666 printed. If the operation didn't finish, for example due to user
667 interruption, also the completion percentage is printed if the
668 size of the input file is known.
669 -Q, --no-warn
671 Don't set the exit status to 2 even if a condition worth a warn‐
672 ing was detected. This option doesn't affect the verbosity
673 level, thus both --quiet and --no-warn have to be used to not
674 display warnings and to not alter the exit status.
675 --robot
677 Print messages in a machine-parsable format. This is intended to
678 ease writing frontends that want to use xz instead of liblzma,
679 which may be the case with various scripts. The output with this
680 option enabled is meant to be stable across xz releases. Cur‐
681 rently --robot is implemented only for --info-memory and --ver‐
682 sion, but the idea is to make it usable for actual compression
683 and decompression too.
684 --info-memory
686 Display the current memory usage limit in human-readable format
687 on a single line, and exit successfully. To see how much RAM xz
688 thinks your system has, use --memory=100% --info-memory. To get
689 machine-parsable output (memory usage limit as bytes without
690 thousand separators), specify --robot before --info-memory.
691 -h, --help
693 Display a help message describing the most commonly used
694 options, and exit successfully.
695 -H, --long-help
697 Display a help message describing all features of xz, and exit
698 successfully
699 -V, --version
701 Display the version number of xz and liblzma in human readable
702 format. To get machine-parsable output, specify --robot before
703 --version.
704
706 0 All is good.
707 1 An error occurred.
709 2 Something worth a warning occurred, but no actual errors
711 occurred.
712 Notices (not warnings or errors) printed on standard error don't affect
714 the exit status.
715
717 XZ_OPT A space-separated list of options is parsed from XZ_OPT before
718 parsing the options given on the command line. Note that only
719 options are parsed from XZ_OPT; all non-options are silently
720 ignored. Parsing is done with getopt_long(3) which is used also
721 for the command line arguments.
722
724 The command line syntax of xz is practically a superset of lzma,
725 unlzma, and lzcat as found from LZMA Utils 4.32.x. In most cases, it is
726 possible to replace LZMA Utils with XZ Utils without breaking existing
727 scripts. There are some incompatibilities though, which may sometimes
728 cause problems.
729 Compression preset levels
731 The numbering of the compression level presets is not identical in xz
732 and LZMA Utils. The most important difference is how dictionary sizes
733 are mapped to different presets. Dictionary size is roughly equal to
734 the decompressor memory usage.
735 Level xz LZMA Utils
737 -1 64 KiB 64 KiB
738 -2 512 KiB 1 MiB
739 -3 1 MiB 512 KiB
740 -4 2 MiB 1 MiB
741 -5 4 MiB 2 MiB
742 -6 8 MiB 4 MiB
743 -7 16 MiB 8 MiB
744 -8 32 MiB 16 MiB
745 -9 64 MiB 32 MiB
746 The dictionary size differences affect the compressor memory usage too,
748 but there are some other differences between LZMA Utils and XZ Utils,
749 which make the difference even bigger:
750 Level xz LZMA Utils 4.32.x
752 -1 2 MiB 2 MiB
753 -2 5 MiB 12 MiB
754 -3 13 MiB 12 MiB
755 -4 25 MiB 16 MiB
756 -5 48 MiB 26 MiB
757 -6 94 MiB 45 MiB
758 -7 186 MiB 83 MiB
759 -8 370 MiB 159 MiB
760 -9 674 MiB 311 MiB
761 The default preset level in LZMA Utils is -7 while in XZ Utils it is
763 -6, so both use 8 MiB dictionary by default.
764 Streamed vs. non-streamed .lzma files
766 Uncompressed size of the file can be stored in the .lzma header. LZMA
767 Utils does that when compressing regular files. The alternative is to
768 mark that uncompressed size is unknown and use end of payload marker to
769 indicate where the decompressor should stop. LZMA Utils uses this
770 method when uncompressed size isn't known, which is the case for exam‐
771 ple in pipes.
772 xz supports decompressing .lzma files with or without end of payload
774 marker, but all .lzma files created by xz will use end of payload
775 marker and have uncompressed size marked as unknown in the .lzma
776 header. This may be a problem in some (uncommon) situations. For exam‐
777 ple, a .lzma decompressor in an embedded device might work only with
778 files that have known uncompressed size. If you hit this problem, you
779 need to use LZMA Utils or LZMA SDK to create .lzma files with known
780 uncompressed size.
781 Unsupported .lzma files
783 The .lzma format allows lc values up to 8, and lp values up to 4. LZMA
784 Utils can decompress files with any lc and lp, but always creates files
785 with lc=3 and lp=0. Creating files with other lc and lp is possible
786 with xz and with LZMA SDK.
787 The implementation of the LZMA1 filter in liblzma requires that the sum
789 of lc and lp must not exceed 4. Thus, .lzma files which exceed this
790 limitation, cannot be decompressed with xz.
791 LZMA Utils creates only .lzma files which have dictionary size of 2^n
793 (a power of 2), but accepts files with any dictionary size. liblzma
794 accepts only .lzma files which have dictionary size of 2^n or 2^n +
795 2^(n-1). This is to decrease false positives when detecting .lzma
796 files.
797 These limitations shouldn't be a problem in practice, since practically
799 all .lzma files have been compressed with settings that liblzma will
800 accept.
801 Trailing garbage
803 When decompressing, LZMA Utils silently ignore everything after the
804 first .lzma stream. In most situations, this is a bug. This also means
805 that LZMA Utils don't support decompressing concatenated .lzma files.
806 If there is data left after the first .lzma stream, xz considers the
808 file to be corrupt. This may break obscure scripts which have assumed
809 that trailing garbage is ignored.
810
812 Compressed output may vary
813 The exact compressed output produced from the same uncompressed input
814 file may vary between XZ Utils versions even if compression options are
815 identical. This is because the encoder can be improved (faster or bet‐
816 ter compression) without affecting the file format. The output can vary
817 even between different builds of the same XZ Utils version, if differ‐
818 ent build options are used.
819 The above means that implementing --rsyncable to create rsyncable .xz
821 files is not going to happen without freezing a part of the encoder
822 implementation, which can then be used with --rsyncable.
823 Embedded .xz decompressors
825 Embedded .xz decompressor implementations like XZ Embedded don't neces‐
826 sarily support files created with check types other than none and
827 crc32. Since the default is --check=crc64, you must use --check=none
828 or --check=crc32 when creating files for embedded systems.
829 Outside embedded systems, all .xz format decompressors support all the
831 check types, or at least are able to decompress the file without veri‐
832 fying the integrity check if the particular check is not supported.
833 XZ Embedded supports BCJ filters, but only with the default start off‐
835 set.
836
838 xzdec(1), gzip(1), bzip2(1)
839 XZ Utils: <http://tukaani.org/xz/>
841 XZ Embedded: <http://tukaani.org/xz/embedded.html>
842 LZMA SDK: <http://7-zip.org/sdk.html>
843Tukaani 2010-03-07 XZ(1)