# Installing

This package is uploaded to PyPI at https://pypi.python.org/pypi/zstandard. So, to install this package:

    $ pip install zstandard

Binary wheels are made available for some platforms. If you need to install from a source distribution, all you should need is a working C compiler and the Python development headers/libraries. On many Linux distributions, you can install a `python-dev` or `python-devel` package to provide these dependencies.

Packages are also uploaded to Anaconda Cloud at https://anaconda.org/indygreg/zstandard. See that URL for how to install this package with `conda`.

## Requirements

This package is designed to run with Python 3.8, 3.9, 3.10, and 3.11 on common platforms (Linux, Windows, and OS X). On PyPy (both PyPy2 and PyPy3) we support version 6.0.0 and above. x86 and x86_64 are well-tested on Windows. Only x86_64 is well-tested on Linux and macOS.

## CFFI Backend

In order to build/run the CFFI backend/bindings (as opposed to the C/Rust backend/bindings), you will need the `cffi` package installed. The `cffi` package is listed as an optional dependency in `setup.py` and may not get picked up by your packaging tools.

If you wish to use the CFFI backend (or have to use it since your Python distribution doesn’t support compiled extensions using the Python C API - this is the case for PyPy for example), be sure you have the `cffi` package installed.

One way to do this is to depend on the `zstandard[cffi]` dependency. e.g. `pip install 'zstandard[cffi]'` or add `zstandard[cffi]` to your pip requirements file.

## Legacy Format Support

To enable legacy zstd format support which is needed to handle files compressed with zstd < 1.0 you need to provide an installation option:

    $ pip install zstandard --install-option="--legacy"

and since pip 7.0 it is possible to have the following line in your requirements.txt:

    zstandard --install-option="--legacy"

## All Install Arguments

`setup.py` accepts the following arguments for influencing behavior:

`--legacy`

  Enable legacy zstd format support in order to read files produced with zstd < 1.0.

`--system-zstd`

  Attempt to link against the zstd library present on the system instead of the version distributed with the extension.

  The Python extension only supports linking against a specific version of zstd. So if the system version differs from what is expected, a build or runtime error will result.

`--warning-as-errors`

  Treat all compiler warnings as errors.

`--no-c-backend`

  Do not compile the C-based backend.

`--no-cffi-backend`

  Do not compile the CFFI-based backend.

`--rust-backend`

  Compile the Rust backend (not yet feature complete).

If you invoke `setup.py`, simply pass the aforementioned arguments. e.g. `python3.9 setup.py --no-cffi-backend`. If using `pip`, use the `--install-option` argument. e.g. `python3.9 -m pip install zstandard --install-option --warning-as-errors`. Or in a pip requirements file: `zstandard --install-option="--rust-backend"`.

In addition, the following environment variables are recognized:

`ZSTD_EXTRA_COMPILER_ARGS`

  Extra compiler arguments to compile the C backend with.

`ZSTD_WARNINGS_AS_ERRORS`

  Equivalent to `setup.py --warnings-as-errors`.

## Building Against External libzstd

By default, this package builds and links against a single file `libzstd` bundled as part of the package distribution. This copy of `libzstd` is statically linked into the extension.

It is possible to point `setup.py` at an external (typically system provided) `libzstd`. To do this, simply pass `--system-zstd` to `setup.py`. e.g.

`python3.9 setup.py --system-zstd` or `python3.9 -m pip install zstandard --install-option="--system-zstd"`.

When building against a system libzstd, you may need to specify extra compiler arguments to help Python’s build system find the external library. These can be specified via the `ZSTD_EXTRA_COMPILER_ARGS` environment variable. e.g. `ZSTD_EXTRA_COMPILER_ARGS="-I/usr/local/include" python3.9 setup.py --system-zstd`.

`python-zstandard` can be sensitive about what version of `libzstd` it links against. For best results, point this package at the exact same version of `libzstd` that it bundles. See the bundled `zstd/zstd.h` or `zstd/zstd.c` for which version that is.

When linking against an external `libzstd`, not all package features may be available. Notably, the `multi_compress_to_buffer()` and `multi_decompress_to_buffer()` APIs are not available, as these rely on private symbols in the `libzstd` C source code, which require building against private header files to use.