Installation Guide

This document provides detailed installation instructions for Torch-RecHub, including stable and development versions.

System Requirements

Before installing Torch-RecHub, ensure your system meets the following requirements:

• Python 3.9+
• PyTorch 1.10+ (choose the CPU, NVIDIA CUDA, AMD ROCm, or Huawei Ascend NPU build for your device)
• NumPy
• Pandas
• Scikit-learn

Installation Methods

PyTorch builds are tightly coupled with your operating system, hardware, driver, and runtime versions. CPU users can install Torch-RecHub directly. NVIDIA CUDA, AMD ROCm, and Huawei Ascend NPU users should first choose a compatible PyTorch build using the PyTorch installation selector, AMD ROCm / PyTorch compatibility guide, or Huawei Ascend NPU / PyTorch compatibility guide. Hardware-specific commands change over time, so use the command currently generated by the official documentation.

Stable Version (Recommended)

The simplest way to install is via pip:

# CPU environments install the declared PyTorch dependency automatically
python -m pip install torch-rechub

# CUDA / ROCm / NPU environments: install the matching PyTorch build first,
# then install Torch-RecHub
python -m pip install torch-rechub

Optional Features

The default installation contains only the core training dependencies. Install extras as needed:

Use case	Command
Generative models	python -m pip install "torch-rechub[generative]"
Streaming Parquet data	python -m pip install "torch-rechub[bigdata]"
ONNX export and quantization	python -m pip install "torch-rechub[onnx]"
Model visualization	python -m pip install "torch-rechub[visualization]"
Experiment tracking	python -m pip install "torch-rechub[tracking]"
Unified vector-index factory (Annoy + Faiss + Milvus)	python -m pip install "torch-rechub[annoy,faiss,milvus]"
All optional features	python -m pip install "torch-rechub[all]"

The current torch_rechub.serving package imports Annoy, Faiss, and Milvus backends during initialization. To use from torch_rechub.serving import builder_factory, install all three vector-index extras; installing only one backend is currently insufficient for this unified entry point.

Latest Development Version

To install the development version with the latest features:

# Install uv first (if not already installed)
python -m pip install uv

# Clone and install
git clone https://github.com/datawhalechina/torch-rechub.git
cd torch-rechub

# Create .venv, install locked dependencies, and install this project editable
uv sync

CUDA, ROCm, and NPU development environments still need a compatible PyTorch/runtime combination selected from the official compatibility guides. Do not blindly reuse wheel URLs from another machine.

Development Environment Setup

If you want to contribute to Torch-RecHub or work with the source code:

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/torch-rechub.git
cd torch-rechub

# 2. Install dependencies and set up environment
uv sync

# 3. Run tests (uv sync already installs this project editable)
uv run pytest

Verify Installation

To verify that Torch-RecHub is correctly installed:

import torch_rechub
print(torch_rechub.__version__)

To verify the PyTorch installation and device detection as well:

import torch

print(torch.__version__)
print("CUDA available:", torch.cuda.is_available())

Or run a simple example:

# cd into the script directory first (scripts use relative data paths)
cd examples/matching
python run_ml_dssm.py

Troubleshooting

PyTorch Installation

If you need a hardware-specific build, use the official compatibility references linked above.

NVIDIA GPU Support

Use the PyTorch installation selector to generate a command for your operating system and CUDA environment. Verify the result with torch.cuda.is_available() in the same Python environment.

AMD GPU Support (ROCm)

First confirm the supported operating system, GPU architecture, ROCm, and PyTorch combination in the AMD ROCm / PyTorch compatibility guide, then use the corresponding official installation command.

NPU Support (Huawei Ascend)

Torch-RecHub supports Huawei Ascend NPU devices, tested on Huawei Ascend 910B.

Please install Ascend-compatible PyTorch and torch-npu versions. For version compatibility details, refer to Huawei Ascend NPU / PyTorch versions.

After installation, import torch_npu in your code, then specify the device in the Trainer:

import torch_npu
from torch_rechub.trainers import CTRTrainer

trainer = CTRTrainer(model, device='npu:0')

Common Issues

If you encounter any installation issues:

1. Check GitHub Issues
2. Create a new Issue with detailed error messages and system information
3. Refer to the FAQ