# User Guide

The 7z file format is a popular archive and compression format in recent days. This module provides tools to read, write and list 7z file. Features is not implemented to update and append a 7z file. py7zr does not support self-extracting archive, aka. SFX file, and only support plain 7z archive file.

## Getting started

### Install

The py7zr is written by Python and can be downloaded from PyPI(aka. Python Package Index) using standard ‘pip’ command as like follows;

    $ pip install py7zr

The py7zr depends on several external libraries. You should install these libraries with py7zr. There are PyCryptodomex, PyPPMd, pybcj, texttable, and multivolumefile. There are also dependency whether Brotli or BrotliCFFI depends on your python flavour. The library backports.zstd is a dependency for Python before 3.14. These packages are automatically installed when installing with `pip` command.

### Dependencies

There are several dependencies to support algorithms and CLI expressions.

Package | Purpose
--- | ---
PyCryptodomex | 7zAES encryption
backports.zstd | ZStandard compression for Python before 3.14
PyPPMd | PPMd compression
Brotli | Brotli compression (CPython)
BrotliCFFI | Brotli compression (PyPy)
inflate64 | Enhanced deflate compression
pybcj | BCJ filters
multivolumefile | Multi-volume archive read/write
texttable | CLI formatter

Note

There is known issue when you run `py7zr` on Windows platform. issue#527 report that when installed on Azure VM Windows, it failed to import Brotli library even when `pip install` was successfully executed. It is because Brotli library depends `vc_redist.x64` Microsoft system library which should be come with python distribution, but Brotli library does not find the DLL in search path on certain environment. Please check details at Brotli Issue#782

Current `py7zr` detect the import failure, and raise exception only when user try to compress/decompress with Brotli compression algorithm.

### Run Command

‘py7zr’ is a command script. You can run extracting a target file target.7z then command line become as such as follows;

    $ py7zr x target.7z

When you want to create an archive from a files and directory under the current directory ‘d’, command line become as such as follows;

    $ py7zr c target.7z  d/

## Command-Line Interfaces

The `py7zr` module provides a simple command-line interface to interact with 7z archives.

If you want to extract a 7z archive into the specified directory, use the `x` subcommand:

    $ python -m py7zr x monty.7z target-dir/
    $ py7zr x monty.7z

For a list of the files in a 7z archive, use the `l` subcommand:

    $ python -m py7zr l monty.7z
    $ py7zr l monty.7z

### Command-line options

l <7z file>

  List files in a 7z file.

x <7z file> [<output_dir>] [--files <file1> ... <fileN>]

  Extract 7z file into target directory. If `output_dir` is specified, py7zr will extract files into the specified directory. Use `--files` to extract only the specified archive members.

c <7z file> <base_dir>

  Create 7zip archive from base_directory

a <7z file> <base_dir>

  Append files from base_dir to existent 7zip archive.

i <7z file>

  Show archive information of specified 7zip archive.

t <7z file>

  Test whether the 7z file is valid or not.

### Common command options

-P --password

  Extract, list or create password protected archive. py7zr will prompt user input.

--verbose

  Show verbose debug log.

### Create command options

-v | --volume {Size}[b|k|m|g]

  Create multi-volume archive with Size. Usable with ‘c’ sub-command.

## Programming APIs

### Extraction

Here is a simple example to extract a 7-zip archive using the python programming language.

    import py7zr
    with py7zr.SevenZipFile("Archive.7z", 'r') as archive:
        archive.extractall(path="/tmp")

This example extracts the contents of “Archive.7z” into the “/tmp” directory. Utilizing the built-in context manager makes the syntax clean and concise.

### Make archive

Here is a simple example to make 7-zip archive.

    import py7zr
    with py7zr.SevenZipFile("Archive.7z", 'w') as archive:
        archive.writeall("target/")

### Append files to archive

Here is a simple example to append some files into existent 7-zip archive.

    import py7zr
    with py7zr.SevenZipFile("Archive.7z", 'a') as archive:
        archive.write("additional_file.txt")

### Extraction from multi-volume archive

You should concatenate multi-volume archives into single archive file before call py7zr, or consider using files wrapping class that handle multiple files as a virtual single file, (ex. multivolumefile library)

    import py7zr
    filenames = ['example.7z.0001', 'example.7z.0002']
    with open('result.7z', 'ab') as outfile:  # append in binary mode
        for fname in filenames:
            with open(fname, 'rb') as infile:        # open in binary mode also
                outfile.write(infile.read())
    with py7zr.SevenZipFile("result.7z", "r") as archive:
        archive.extractall()
    os.unlink("result.7z")

Here is another example. This example use multivolumefile library. The multivolumefile library is in pre-alpha status, so it is not recommend to use production system.

    pip install py7zr multivolumefile

When there are files named, ‘example.7z.0001’, ‘example.7z.0002’, and so on, following code will extract multi-volume archive.

    import multivolumefile
    import py7zr
    with multivolumefile.open('example.7z', mode='rb') as target_archive:
        with SevenZipFile(target_archive, 'r') as archive:
            archive.extractall()

### Creation of multi-volume archive

If you want to create multi volume archive using multivolumefile library, following example do it for you.

    import multivolumefile
    import py7zr

    target = pathlib.Path('/target/directory/')
    with multivolumefile.open('example.7z', mode='wb', volume_size=10240) as target_archive:
        with SevenZipFile(target_archive, 'w') as archive:
            archive.writeall(target, 'target')

## Presentation material

See `Introductory presentation(PDF)`, and `Introductory presentation(ODP)`.