Installation

Requirements

  • Python 3.12 or higher

  • CUDA-capable GPU (recommended) or CPU

  • 8GB+ RAM (16GB+ recommended)

  • 50GB+ disk space for models

Installation Methods

From Source

# Clone the repository
git clone https://github.com/yourusername/pipeworks-image-generator.git
cd pipeworks-image-generator

# Install in development mode
pip install -e .

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

# Or install with docs dependencies
pip install -e ".[docs]"

Environment Configuration

Pipeworks uses environment variables for configuration. Create a .env file in your project root:

# Model settings
PIPEWORKS_MODEL_ID=Xkev/Z-Image-Turbo
PIPEWORKS_DEVICE=cuda  # or cpu, mps
PIPEWORKS_TORCH_DTYPE=bfloat16  # or float16, float32

# Directories
PIPEWORKS_MODELS_DIR=./models
PIPEWORKS_OUTPUTS_DIR=./outputs
PIPEWORKS_INPUTS_DIR=./inputs

# Generation defaults
PIPEWORKS_NUM_INFERENCE_STEPS=9
PIPEWORKS_DEFAULT_WIDTH=1024
PIPEWORKS_DEFAULT_HEIGHT=1024

# Gradio UI settings
PIPEWORKS_GRADIO_SERVER_PORT=7860
PIPEWORKS_GRADIO_SERVER_NAME=0.0.0.0

See .env.example in the repository for all available options.

Verification

Verify your installation:

from pipeworks import model_registry, config

# This should print version info
adapter = model_registry.instantiate("Z-Image-Turbo", config)
print("Pipeworks installed successfully!")

Troubleshooting

CUDA Not Available

If you see “CUDA is not available” warnings:

  1. Verify CUDA is installed: nvidia-smi

  2. Install PyTorch with CUDA support: pip install torch --index-url https://download.pytorch.org/whl/cu121

  3. Set PIPEWORKS_DEVICE=cpu to run on CPU

Memory Issues

If you encounter out-of-memory errors:

  1. Reduce batch size

  2. Use PIPEWORKS_TORCH_DTYPE=float16 instead of bfloat16

  3. Close other GPU applications

  4. Set PIPEWORKS_DEVICE=cpu to offload to CPU