Installation - 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:

Clone the repository

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

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
CUDA 11.8
CPU Only

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

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

pip install torch torchvision

CPU-only mode is not recommended for training or inference. Performance will be significantly slower.

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:

Reduce batch size:
lora = m.train_lora(ds, batch_size=1)
Enable gradient checkpointing (coming in Phase 2)

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:

Ensure you have CUDA 11.8 or 12.1 installed

Install build tools:

# Ubuntu/Debian
sudo apt-get install build-essential

# macOS
xcode-select --install

Skip Flash Attention for now:

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

Import Errors

If you get import errors after installation:

Verify installation:
pip show hypergen

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

​System Requirements

Python Version

GPU (Recommended)

VRAM Requirements

Operating System

​Installation Methods

​Install via pip (Recommended)

​Install from Source

​Install with uv (Faster)

​GPU Setup

​CUDA Installation

​Verify GPU Setup

​Dependencies

​Optional Dependencies

​Flash Attention (Recommended)

​xFormers (Alternative Optimization)

​DeepSpeed (Multi-GPU Training)

​Video Models Support

​All Optional Dependencies

​Development Installation

​Troubleshooting

​CUDA Out of Memory

​Installation Fails on Flash Attention

​Import Errors

​macOS Metal (MPS) Support

​Verifying Installation

​Next Steps

Quick Start

Training Guide

Serving Guide

Supported Models

System Requirements

Installation Methods

Install via pip (Recommended)

Install from Source

Install with uv (Faster)

GPU Setup

CUDA Installation

Verify GPU Setup

Dependencies

Optional Dependencies

Flash Attention (Recommended)

xFormers (Alternative Optimization)

DeepSpeed (Multi-GPU Training)

Video Models Support

All Optional Dependencies

Development Installation

Troubleshooting

CUDA Out of Memory

Installation Fails on Flash Attention

Import Errors

macOS Metal (MPS) Support

Verifying Installation

Next Steps