# higgsfield: multi-node LLM training without the crying

> higgsfield-ai/higgsfield is an Apache-2.0 GPU orchestration layer and training framework for billion- to trillion-parameter models. It asks for Ubuntu nodes with SSH and passwordless sudo, and it installs from PyPI.

**higgsfield-ai/higgsfield** — Fault-tolerant, highly scalable GPU orchestration, and a machine learning framework designed for training models with billions to trillions of parameters

- Repository: https://github.com/higgsfield-ai/higgsfield
- Stars: 5,822 · Forks: 1,042
- Language: Jupyter Notebook
- License: Apache-2.0
- Published: 2026-09-14 · Updated: 2026-09-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/higgsfield-ai-higgsfield

## What higgsfield solves, and for whom

Training a 70B model across several machines means solving problems that have nothing to do with machine learning. Which node runs which rank. Who gets the GPUs when two experiments want them at once. What happens when a node dies mid-epoch. Which PyTorch and driver combination was installed on that box three months ago. higgsfield is aimed at teams that already have the hardware and want the orchestration handled: the README describes it as a GPU workload manager and machine learning framework with five functions, from allocating exclusive and non-exclusive access to nodes through to a queue for running experiments and GitHub Actions integration.

The intended user is not someone renting a single A100 by the hour. It is a lab or company with a standing pool of nodes, an SSH-reachable fleet, and a training script they want to run repeatedly without rewriting the launch layer each time. The README's compatibility section is blunt about the requirements: Ubuntu, SSH access, and a non-root user with sudo privileges where no password is required. If your infrastructure cannot meet that, the project is not for you, and no amount of configuration will fix it.

## The mechanism: nodes, Git, and a queue

The README's "How it's all done?" section describes a four-step loop. First, the tooling is installed on your servers: Docker, your project's deploy keys, and the higgsfield binary. Second, it generates deploy and run workflows for your experiments. Third, once those workflows reach GitHub, the code is deployed automatically onto your nodes. Fourth, you launch experiments and save checkpoints through the run UI that GitHub exposes.

That is a GitOps-shaped design. The repository is the control plane, and GitHub Actions is the executor. The queue for resource contention sits between the workflow and the nodes, so two experiments submitted at once do not both grab the same GPUs. The pyproject.toml shows the transport layer underneath: asyncssh with bcrypt, libnacl and pyopenssl extras, plus cryptography and libsodium. Remote execution happens over SSH, with keys handled by the project rather than by your shell history.

The framework side is deliberately thin. The README states the project follows the standard PyTorch workflow and that you can bring deepspeed, accelerate, or your own sharding implementation. The stated support is for the ZeRO-3 deepspeed API and PyTorch's fully sharded data parallel API. That is a real constraint dressed as flexibility: if your training loop depends on a different parallelism scheme, the framework's own model wrappers will not help you, and you are back to writing the distributed code yourself.

## Installing higgsfield and running a first experiment

The README gives a single install command, pinned to version 0.0.3. Note that the repository's pyproject.toml also declares version 0.0.3, while the most recent release listed is v0.0.4-rc, a release candidate. Pinning to 0.0.3 is the documented path.

```bash
$ pip install higgsfield==0.0.3
```

After installation, the pyproject.toml declares a console script named higgsfield that maps to higgsfield.internal.main:cli, so the higgsfield command becomes available in your environment.

The README's training example is the shortest description of the intended API. It imports Llama70b from higgsfield.llama, LlamaLoader from higgsfield.loaders, and an experiment decorator from higgsfield.experiment.

```python
from higgsfield.llama import Llama70b
from higgsfield.loaders import LlamaLoader
from higgsfield.experiment import experiment

import torch.optim as optim
from alpaca import get_alpaca_data

@experiment("alpaca")
def train(params):
    model = Llama70b(zero_stage=3, fast_attn=False, precision="bf16")
    optimizer = optim.AdamW(model.parameters(), lr=1e-5, weight_decay=0.0)
    dataset = get_alpaca_data(split="train")
    train_loader = LlamaLoader(dataset, max_words=2048)
    for batch in train_loader:
        optimizer.zero_grad()
        loss = model(batch)
        loss.backward()
        optimizer.step()
    model.push_to_hub('alpaca-70b')
```

The decorator names the experiment, the model wrapper takes the sharding and precision settings, and the loader handles tokenisation up to a word limit. What you should see after running this is a training loop that executes across the allocated nodes and, at the end, a checkpoint pushed to the Hugging Face Hub under the name you pass to push_to_hub.

Before any of that, the README points to setup.md for the real work: initialising the project, setting up the environment, setting up Git, setting up your nodes, running a first experiment, and deploying. Those steps are not reproduced in the README itself, and the README does not document what happens if node setup fails partway through.

## Where higgsfield stops being the right tool

The compatibility list is the first hard boundary. Nodes must run Ubuntu, must be reachable over SSH, and must have a non-root user with passwordless sudo. That last requirement is a security posture, not a checkbox. On a shared cluster where sudo is audited or withheld, higgsfield cannot install Docker or its own binary, and the whole model collapses.

The tested clouds are Azure, LambdaLabs and FluidStack. The README invites issues for other clouds, which is an honest admission that the install path is cloud-specific and that the maintainers have not validated it elsewhere. If you run on-premise with a custom image, or on a provider whose images ship without passwordless sudo, expect to debug the node setup yourself.

The framework coverage is narrower than the orchestration. ZeRO-3 deepspeed and PyTorch FSDP are the stated supported paths. Anything else, including tensor parallelism implemented by hand or a different distributed backend, falls outside what the wrappers provide. The README frames this as freedom to bring your own sharding, but the practical effect is that the framework's value shrinks the further your model architecture sits from a standard Llama-style transformer.

There is also a version mismatch worth flagging. The README pins pip install higgsfield==0.0.3, the package metadata says 0.0.3, and the newest release is v0.0.4-rc. A release candidate is not a stable target, and the documentation has not been updated to it. That is a small signal about release discipline, but it is the kind of thing that costs an afternoon when you assume the newest tag is the documented one.

## higgsfield against a plain PyTorch and torchrun setup

The obvious alternative is not another orchestration product. It is doing nothing: launching training with torchrun or deepspeed's own launcher across a list of hosts, and managing the environment by hand.

The difference in approach is where the state lives. With torchrun, the host list is an argument you pass at launch, and the environment is whatever you installed on each box. Nothing records which driver version ran with which commit. higgsfield moves that state into the repository: the README describes generating deploy and run workflows, deploying code through GitHub, and launching experiments through the run UI. The queue and the node allocation live in the same place as the code, which is what makes the environment-hell and config-hell arguments in the README land.

The cost is coupling. A torchrun setup can be started from a laptop against any reachable host in seconds. higgsfield wants GitHub in the loop, a project initialised, Git configured, nodes registered, and the binary installed everywhere. For a one-off fine-tune on two boxes, that is more machinery than the job deserves. For a team running the same pipeline weekly across a fixed fleet, the trade flips.

## Maintenance, upgrades, and the Apache-2.0 terms

The repository is not archived, and the last push was on 2026-09-14, three days before this writing. That is a current codebase. The release history is thinner: v0.0.4-rc dates from 2024-03-23, and the version in pyproject.toml is still 0.0.3. So the code moves, but the tagged releases have not kept pace with it, and the README's install instruction points at the older number. Anyone tracking the project should read the default branch rather than assume the latest tag is current.

The upgrade cost is dominated by the node fleet, not the package. Upgrading higgsfield means reinstalling the binary across every node, and the README's setup flow installs Docker, deploy keys and the binary together. A version bump is therefore a fleet operation, and any drift between nodes is a class of bug the framework does not appear to detect on its own.

Licensing is Apache-2.0, declared both in the repository and in pyproject.toml, with a NOTICES.md file at the top level alongside LICENSE. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, with attribution and notice requirements. The practical implication for a company embedding higgsfield in an internal training platform is that the licence itself is unlikely to be the blocker; the NOTICES.md file is worth reading alongside it, and your legal team should make the call rather than this article.

## Conclusion

Adopt higgsfield if you own or rent a fixed set of Ubuntu GPU nodes with SSH and passwordless sudo, and you want a queue, a CLI and Git-triggered deploys around a standard PyTorch loop. Do not adopt it if you need a managed control plane, if your scheduler is Kubernetes or Slurm, or if you cannot give a non-root account sudo without a password. Before committing, verify the setup.md steps against your cloud, confirm the pinned pip version actually resolves on your Python, and check whether the framework's distributed model API covers the sharding strategy your model needs.

## FAQ

### How do I install the higgsfield CLI?

The README gives one command, pip install higgsfield==0.0.3. The pyproject.toml declares a console script named higgsfield pointing at higgsfield.internal.main:cli, so the command is available once the package is installed. Node-side setup is documented separately in setup.md.

### Can I use Higgsfield for free?

The library is published under Apache-2.0 and installs from PyPI, so the software itself carries no listed fee. What it does require is your own hardware: Ubuntu nodes with SSH access and a non-root user with passwordless sudo.

### Is Higgs field AI legit?

The repository is public, licensed Apache-2.0, and not archived, with the last push on 2026-09-14. It ships a README, setup.md, tutorial.md and a tutorials directory. Whether it fits your infrastructure is a separate question from whether the project is real.

### How much does higgsfield cost?

The README lists no pricing, and the repository contains no pricing information. The package is Apache-2.0 and installs from PyPI; the cost of running it is the cost of the GPU nodes you point it at.

## Sources

- [higgsfield-ai/higgsfield on GitHub](https://github.com/higgsfield-ai/higgsfield)
- [Issues](https://github.com/higgsfield-ai/higgsfield/issues)
- [License: Apache-2.0](https://github.com/higgsfield-ai/higgsfield/blob/main/LICENSE)
- [README](https://github.com/higgsfield-ai/higgsfield/blob/main/README.md)
- [Releases](https://github.com/higgsfield-ai/higgsfield/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/higgsfield-ai-higgsfield