Setup Guides

This guide will help you set up a development environment for cz-benchmarks on macOS, Linux, or Windows.

Prerequisites

1. Install Python and a Tool for Environment/Dependency Management
   Make sure you have Python 3.10+ installed.
   There are several tools you can use for managing Python environments and dependencies:

   • pip and venv

   • Miniconda or Anaconda

   • uv (described below)

   Choose the tool you prefer and make sure it is installed.

2. Install Build Tools and Python Headers
   Some dependencies require C/C++ compilers and Python headers.

   • macOS: Install Xcode Command Line Tools:

     xcode-select --install
     

   • Linux (Debian/Ubuntu): Install compilers and Python dev headers:

     sudo apt-get update
     sudo apt-get install build-essential python3-dev
     

   • Windows: Install Build Tools for Visual Studio (select “C++ build tools” during installation).

Setting Up the Environment

1. Create a Virtual Environment
   Using a virtual environment is strongly recommended to isolate dependencies.
   Example using venv:

   python -m venv venv
   

   Activate the environment:

   • macOS/Linux:

     source venv/bin/activate
     

   • Windows:

     venv\Scripts\activate
     

2. Install Dependencies
   Install the required Python packages in editable mode with development dependencies:

   pip install -e ".[dev]"
   

   Note: On some systems (especially macOS and Linux), you may need to ensure system C/C++ build tools and Python header files are present before installing dependencies such as hnswlib (see above).

---

Using uv for Dependency Management

uv is an alternative tool that simplifies Python dependency management.

1. Install uv
   You can use pip to install uv:

   pip install uv
   

2. Install the Required Python Version (Optional)
   If your Python version doesn’t match the project requirements, uv can help install/manage it:

   uv python install
   

3. Sync Dependencies
   To install all project dependencies, including optional “extras”:

   uv sync --all-extras
   

4. Troubleshooting hnswlib Installations

   If you encounter an error involving Python.h (e.g., fatal error: Python.h: No such file or directory), make sure Python development headers and static libraries are installed:

   • Linux (Debian/Ubuntu):

     sudo apt-get install python3-dev
     

   • macOS: Ensure Xcode Command Line Tools are installed (xcode-select --install).

   • Windows: Ensure Visual Studio C++ Build Tools are present.

💡 Tip: For more details, see the official uv installation guide.