Skip to main content

​
Overview

Zstandard is designed to be highly portable and supports major operating systems including Linux, macOS, Windows, and various Unix-like systems.

​
Linux

​
Standard Build

On most Linux distributions with standard make or gmake: 
make
make install

​
Installation Paths

Default installation follows GNU standards: 
make install PREFIX=/usr/local
This installs:
  • Binaries: /usr/local/bin/
  • Libraries: /usr/local/lib/
  • Headers: /usr/local/include/
  • Man pages: /usr/local/share/man/

​
Multiarch Support

For multiarch systems (Debian/Ubuntu), libraries should be installed to architecture-specific directories: 
make install PREFIX=/usr LIBDIR=/usr/lib/x86_64-linux-gnu
This ensures correct installation paths and generates proper pkg-config files.

​
Multithreading on POSIX

Multithreading on Linux requires:
  1. Build macro: -DZSTD_MULTITHREAD
  2. Link with pthread: -pthread
Example: 
# Compile with multithreading
gcc -DZSTD_MULTITHREAD -pthread -o myapp myapp.c -lzstd

​
pkg-config Integration

After installation, use pkg-config: 
# Get compilation flags
pkg-config --cflags libzstd

# Get linking flags
pkg-config --libs libzstd

# Compile with pkg-config
gcc -o myapp myapp.c $(pkg-config --cflags --libs libzstd)
For multithreaded static library, set MT=1 when installing: 
make install MT=1

​
macOS

​
Build from Source

make
make install

​
Homebrew

Install via Homebrew: 
brew install zstd

​
Dynamic Library Differences

macOS uses different shared library conventions:
  • Extension: .dylib instead of .so
  • Versioning: libzstd.1.dylib (major version)
  • Install name: Uses -install_name instead of -soname
The Makefile automatically handles these differences: 
ifeq ($(UNAME_TARGET_SYSTEM), Darwin)
  SHARED_EXT = dylib
  SHARED_EXT_MAJOR = $(LIBVER_MAJOR).$(SHARED_EXT)
  SONAME_FLAGS = -install_name $(LIBDIR)/libzstd.$(SHARED_EXT_MAJOR)
endif

​
Universal Binaries (Apple Silicon + Intel)

Build fat binaries supporting both architectures using CMake: 
cmake -S . -B build-cmake \
  -G Ninja \
  -DCMAKE_OSX_ARCHITECTURES="x86_64;x86_64h;arm64" \
  -DZSTD_FRAMEWORK=ON

cd build-cmake
ninja
sudo ninja install
This creates binaries that run natively on:
  • Apple Silicon (M1/M2/M3)
  • Intel Macs (x86_64)
CMake versions 3.14+ are recommended for iOS-derived platforms.

​
iOS Framework

Build iOS framework: 
# For modern CMake (3.14+)
cmake -S . -B build-cmake \
  -DZSTD_FRAMEWORK=ON \
  -DCMAKE_SYSTEM_NAME=iOS

# For older CMake with iOS-CMake toolchain
cmake -B build -G Xcode \
  -DCMAKE_TOOLCHAIN_FILE=<Path To ios.toolchain.cmake> \
  -DPLATFORM=OS64 \
  -DZSTD_FRAMEWORK=ON

​
Windows

​
MinGW + MSYS

Build with MinGW: 
make libzstd
This creates:
  • dll\libzstd.dll - Dynamic library
  • dll\libzstd.lib - Import library (for Visual C++)

​
Compiling Applications

With MinGW/gcc: 
gcc -Iinclude/ test-dll.c -o test-dll dll\libzstd.dll
The executable requires dll\libzstd.dll at runtime.

​
Visual Studio

Multiple options available in the build/ directory:

​
vcpkg Integration

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg integrate install
.\vcpkg install zstd
vcpkg automatically handles:
  • Multi-architecture builds
  • Debug/Release configurations
  • Integration with Visual Studio

​
AIX

On AIX systems, the Makefile automatically adjusts: 
ifeq ($(UNAME_TARGET_SYSTEM), AIX)
  SONAME_FLAGS =
endif
Build normally: 
make
make install

​
Cross-Platform Considerations

​
Target System Detection

The build system detects the target platform: 
TARGET_SYSTEM ?= $(OS)

ifneq (,$(filter Windows%,$(TARGET_SYSTEM)))
  EXT =.exe
else
  EXT =
endif

​
Cross-Compilation

When cross-compiling from Linux to Windows: 
make TARGET_SYSTEM=Windows CC=x86_64-w64-mingw32-gcc
For other cross-compilation scenarios, set:
  • CC - Cross compiler
  • TARGET_SYSTEM - Target OS
  • UNAME_TARGET_SYSTEM - Target uname output

​
Endianness

Zstandard automatically handles endianness. All magic numbers are read/written using little-endian convention, with automatic conversion on big-endian systems.

​
Compiler-Specific Features

​
BMI2 Instructions (x86_64)

# Force BMI2 instructions
make STATIC_BMI2=1

# Disable BMI2
make STATIC_BMI2=0
BMI2 instructions improve decompression performance on supported CPUs.

​
Intrinsics

Disable explicit intrinsics: 
make ZSTD_NO_INTRINSICS=1
Compiler builtins are still used.

​
Assembly Optimizations

On x86_64 Linux, assembly optimizations are automatically enabled. To disable: 
make CFLAGS="-DZSTD_DISABLE_ASM"

​
Memory Usage

​
Decoder Buffer Size

Control internal decompression buffer size: 
# Reduce to 32 KB (default: 64 KB)
make CFLAGS="-DZSTD_DECODER_INTERNAL_BUFFER=32768"
Smaller values reduce memory footprint but may slightly impact decompression speed.

​
Testing

​
Quick Smoke Tests

make check

​
Comprehensive Tests

make test

​
Without Make

If make is unavailable: 
cd tests
export ZSTD_BIN=/path/to/zstd
export DATAGEN_BIN=/path/to/datagen
./playTest.sh

​
Troubleshooting

Ensure you’re linking with -pthread:
gcc -o myapp myapp.c -lzstd -pthread
For static multithreaded library:
make lib-mt
Ensure libzstd.dll is:
  • In the same directory as your executable
  • In a directory listed in PATH
  • Or statically link instead
Use architecture-specific library directories:
make install PREFIX=/usr LIBDIR=/usr/lib/x86_64-linux-gnu
Some CPUs don’t benefit from BMI2. Disable if needed:
make STATIC_BMI2=0 DYNAMIC_BMI2=0

​
Next Steps

Build Systems

Integrate with Make, CMake, Meson, Bazel, or Buck

C/C++ Integration

Learn the C/C++ API

Build docs developers (and LLMs) love

Get started for freeTalk to us