Setup Guides
macOS Development Setup
For macOS users, follow these steps to set up your development environment:
Prerequisites
Install Tool for Python Environment and Dependency Management
There are multiple tools for managing Python environments and dependencies. Popular ones include pip and venv, Miniconda, and Anaconda. An alternative, uv, is described below.
Choose your favorite and make sure it is correctly installed.
Install Xcode Command Line Tools
Xcode provides essential compiler tools for macOS. Run the following command in your terminal to install it:xcode-select --install
Install Docker
Docker is required for containerized execution. Download and install Docker from the official website. After installation, verify it is working by running:docker run hello-world
Setting Up the Environment
Create a Virtual Environment
It is highly recommended to create a virtual environment to isolate your project dependencies. The steps vary dependeing on the tool, one example is provided below forpip
andvenv
:python -m venv venv source venv/bin/activate # On macOS/Linux venv\Scripts\activate # On Windows
Install Dependencies
Install the required Python packages:
Mac requires an additional dependency, hnswlib
, which should be installed with the package manager.
- Install the package in editable mode with development dependencies:
```bash
pip install -e ".[dev]"
```
Using uv
for Dependency Management
uv
is a tool that simplifies Python dependency management. Follow these steps to set it up:
Install
uv
Usepip
to installuv
:pip install uv
Install the Required Python Version
Ensure the correct Python version is installed for your project:uv python install
Sync Dependencies
Install all required dependencies, including extras, by running:uv sync --all-extras
💡 Tip: For more details, refer to the official
uv
installation guide.
Troubleshooting
Common Issues and Fixes
Command Not Found
Ensure the package is installed and accessible in your shell. If not, reinstall it:pip install czbenchmarks
Docker Fails to Run
Verify Docker is installed and running. Check permissions for your user account. Restart Docker if necessary.Memory Errors
Reduce the dataset size or process the data in smaller batches during inference.Dataset or Model Not Found
Use thelist
commands to verify available datasets and models:czbenchmarks list datasets czbenchmarks list models
Dependency Conflicts
Ensure all dependencies are installed in a clean virtual environment. Recreate the environment if needed.hnswlib package installation error
If the
hnswlib
package fails to install with an error likefatal error: Python.h: No such file or directory
, ensure you have installed Python development headers files and static libraries. On Ubuntu, this can be done viasudo apt-get install python3-dev
.