# Higgsfield

> An open-source, fault-tolerant, highly scalable GPU orchestration and machine learning framework for training models with billions to trillions of parameters.

Higgsfield is an open-source GPU workload manager and machine learning framework built for training massive neural networks — from billions to trillions of parameters — across multi-node clusters. Released under the Apache License 2.0, it is available on GitHub and installable via PyPI. The project targets ML engineers and researchers who need distributed training without the typical configuration overhead.

## What It Is

Higgsfield sits at the intersection of GPU orchestration and ML framework tooling. It manages compute resources across nodes, handles fault tolerance, and provides a simplified Python API for launching and monitoring large-scale training runs. Rather than replacing PyTorch, it wraps and extends it — supporting ZeRO-3 DeepSpeed and PyTorch's Fully Sharded Data Parallel (FSDP) APIs to enable efficient sharding for trillion-parameter models.

## Core Functions

The framework performs five primary jobs according to its README:

- **Resource allocation**: Grants exclusive or non-exclusive access to compute nodes for training tasks.
- **Sharding support**: Integrates ZeRO-3 DeepSpeed and PyTorch FSDP for efficient trillion-parameter model training.
- **Experiment lifecycle management**: Initiates, executes, and monitors training of large neural networks on allocated nodes.
- **Queue management**: Handles resource contention by maintaining an experiment queue.
- **CI/CD integration**: Connects seamlessly with GitHub and GitHub Actions to automate deployment of training code to nodes.

## Setup and Workflow

Higgsfield follows a GitHub-centric deployment model. After installing the package and initializing a project, it installs required tools (Docker, deploy keys, the higgsfield binary) on target servers. It then generates deploy and run workflows for experiments. When code is pushed to GitHub, it automatically deploys to the configured nodes. Experiment runs and checkpoint saving are managed through a GitHub-based UI.

Compatible nodes require Ubuntu, SSH access, and a non-root user with passwordless sudo. The README notes it has been tested on Azure, LambdaLabs, and FluidStack.

## Design Philosophy

Higgsfield explicitly targets two pain points in large-scale ML training:

- **Environment hell**: Eliminates version mismatches across PyTorch, NVIDIA drivers, and data processing libraries by orchestrating reproducible environments.
- **Config hell**: Replaces verbose argument files and YAML-heavy config systems with a minimal `@experiment` decorator interface. A full LLaMA 70B distributed training run can be expressed in roughly 15 lines of Python.

The framework is compatible with DeepSpeed, Hugging Face Accelerate, and custom PyTorch sharding strategies, so teams are not locked into a single training paradigm.

## Update: v0.0.4-rc

The latest release is **v0.0.4-rc**, published on March 23, 2024. The PyPI-published stable version is `0.0.3`. The repository remains active, with the last push recorded in September 2026 per GitHub metadata, and has accumulated over 5,700 stars and 1,000 forks. Primary language in the repository is Jupyter Notebook, reflecting a tutorial and example-heavy structure alongside the core Python package.

## Features
- Fault-tolerant multi-node GPU orchestration
- ZeRO-3 DeepSpeed API support
- PyTorch Fully Sharded Data Parallel (FSDP) support
- Experiment queue management
- GitHub and GitHub Actions CI/CD integration
- Automatic node setup (Docker, deploy keys, higgsfield binary)
- Reproducible environment management
- Minimal @experiment decorator API
- Checkpoint saving and model push to hub
- Support for LLaMA and other large language models
- Compatible with Azure, LambdaLabs, and FluidStack

## Integrations
PyTorch, DeepSpeed, Hugging Face Accelerate, GitHub, GitHub Actions, Docker, LambdaLabs, Azure, FluidStack

## Platforms
CLI, API, DEVELOPER_SDK

## Pricing
Open Source

## Version
v0.0.4-rc

## Links
- Website: https://github.com/higgsfield-ai/higgsfield
- Documentation: https://github.com/higgsfield-ai/higgsfield/blob/main/setup.md
- Repository: https://github.com/higgsfield-ai/higgsfield
- EveryDev.ai: https://www.everydev.ai/tools/higgsfield