Installation

Complete installation guide for HyperGen

System Requirements

Python Version

Python 3.10 or higher

GPU (Recommended)

NVIDIA GPU with CUDA 11.8+

VRAM Requirements

Minimum 8GB, Recommended 16GB+

Operating System

Linux, macOS, or Windows

Installation Methods

Install via pip (Recommended)

The simplest way to install HyperGen:

pip install hypergen

This will install HyperGen and all required dependencies.

Install from Source

For the latest development version or to contribute:

1. Clone the repository

   git clone https://github.com/ntegrals/hypergen.git
   cd hypergen
   

2. Install in editable mode

   pip install -e .
   

   The -e flag installs in editable mode, so changes to the source code are reflected immediately.

Install with uv (Faster)

For faster installation using uv:

uv pip install hypergen

Or from source:

git clone https://github.com/ntegrals/hypergen.git
cd hypergen
uv pip install -e .

GPU Setup

CUDA Installation

HyperGen requires PyTorch with CUDA support for GPU acceleration.

CUDA 12.1

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

Verify GPU Setup

Check that PyTorch can access your GPU:

import torch

print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
print(f"GPU count: {torch.cuda.device_count()}")
if torch.cuda.is_available():
    print(f"GPU name: {torch.cuda.get_device_name(0)}")

Expected output:

CUDA available: True
CUDA version: 12.1
GPU count: 1
GPU name: NVIDIA GeForce RTX 4090

Dependencies

HyperGen automatically installs the following core dependencies:

Package	Version	Purpose
torch	>=2.0.0	Deep learning framework
diffusers	>=0.30.0	Diffusion model pipelines
transformers	>=4.40.0	Text encoders and tokenizers
peft	>=0.8.0	LoRA and parameter-efficient fine-tuning
accelerate	>=0.30.0	Training acceleration
safetensors	>=0.4.0	Safe model serialization
pillow	>=10.0.0	Image processing
numpy	>=1.24.0	Numerical operations
fastapi	>=0.104.0	API server framework
uvicorn	>=0.24.0	ASGI server
pydantic	>=2.0.0	Data validation

Optional Dependencies

Flash Attention (Recommended)

For faster training and inference with attention optimization:

pip install hypergen[flash]

Or manually:

pip install flash-attn>=2.5.0

Flash Attention requires CUDA and may take several minutes to compile on first installation.

xFormers (Alternative Optimization)

Alternative memory-efficient attention implementation:

pip install hypergen[xformers]

Or manually:

pip install xformers>=0.0.25

DeepSpeed (Multi-GPU Training)

For distributed training across multiple GPUs:

pip install hypergen[deepspeed]

Or manually:

pip install deepspeed>=0.14.0

Video Models Support

For CogVideoX and other video diffusion models:

pip install hypergen[video]

Or manually:

pip install av>=12.0.0 opencv-python>=4.9.0

All Optional Dependencies

Install everything at once:

pip install hypergen[all]

This will install all optional dependencies, which may take significant time and disk space.

Development Installation

For contributing to HyperGen:

git clone https://github.com/ntegrals/hypergen.git
cd hypergen

# Install with dev dependencies
pip install -e ".[dev]"

This includes:

• pytest - Testing framework
• pytest-cov - Coverage reporting
• ruff - Linting and formatting

Troubleshooting

CUDA Out of Memory

If you encounter CUDA out of memory errors:

1. Reduce batch size:

   lora = m.train_lora(ds, batch_size=1)
   

2. Enable gradient checkpointing (coming in Phase 2)

3. Use a smaller model or lower precision:

   m = model.load("model_id", torch_dtype="float16")
   

Installation Fails on Flash Attention

Flash Attention requires specific CUDA versions and compilation:

1. Ensure you have CUDA 11.8 or 12.1 installed

2. Install build tools:

   # Ubuntu/Debian
   sudo apt-get install build-essential
   
   # macOS
   xcode-select --install
   

3. Skip Flash Attention for now:

   pip install hypergen
   # Don't install hypergen[flash]
   

Import Errors

If you get import errors after installation:

1. Verify installation:

   pip show hypergen
   

2. Reinstall in a clean environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install hypergen
   

macOS Metal (MPS) Support

For Apple Silicon Macs:

# Use MPS backend instead of CUDA
m = model.load("stabilityai/stable-diffusion-xl-base-1.0")
m.to("mps")

MPS support is experimental. Some features may not work as expected.

Verifying Installation

Test your installation with a quick script:

from hypergen import model, dataset
import torch

print(f"HyperGen installed successfully!")
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")

# Try loading a small model (optional)
# m = model.load("runwayml/stable-diffusion-v1-5")
# print("Model loaded successfully!")

Next Steps

Quick Start

Train your first LoRA in 5 minutes

Training Guide

Learn about LoRA training parameters

Serving Guide

Deploy a model with the API server

Supported Models

See which models are compatible