Python SDK / Bindings

This guide walks you through installing the Python SDK from source.

Prerequisites

Before you begin, ensure your environment meets the following requirements:

• Python: Version 3.9 or higher
• Compiler: A C++17 compatible compiler
• Platform:
  • Linux (x86_64/ARM64)
  • macOS (x86_64/ARM64)
  • Windows (x86_64) — Note: Currently tested with MSVC 2022 (Visual Studio 17.0+) only
• Git: Required to clone the repository with submodules
• scikit-build (installed automatically as a build dependency, but may require manual configuration in some environments)

Install from Source

# Clone the repository
git clone --recurse-submodules https://github.com/alibaba/zvec.git
cd zvec

# Install from source
pip install .

USE_OSS_MIRROR=ON pip install .

(Optional) Build Configuration

Build Directory

If you encounter issues during the build process, try setting a custom build directory for scikit-build. This can help avoid cache inconsistencies and makes it easier to inspect detailed build logs:

export SKBUILD_BUILD_DIR=/tmp/build  # Or other directory

pip install .

After the build attempt, you can examine the contents of /tmp/build (or your chosen directory) to review compiler output and diagnose errors.

Build System

By default, scikit-build uses Ninja as the build system, which automatically compiles using all available CPU cores. To use Unix Makefiles instead, set:

export CMAKE_GENERATOR="Unix Makefiles"

pip install .

• When using Make, you need to manually configure parallel compilation to speed up the build:

  # Option 1: Set parallel level via environment variable
  export CMAKE_BUILD_PARALLEL_LEVEL=32
  export CMAKE_GENERATOR="Unix Makefiles"
  pip install .
  
  # Option 2: Pass parallel flag via config settings
  export CMAKE_GENERATOR="Unix Makefiles"
  pip install . --config-settings=build.tool-args="-j$(nproc)"