# HyperGAN: composable GANs described in JSON and trained from a folder of images

> A PyTorch GAN framework whose architecture lives in a JSON configuration file, with a CLI for training and sampling, a Python API, and a release history that stopped in 2020.

**HyperGAN/HyperGAN** — Composable GAN framework with api and user interface

- Repository: https://github.com/HyperGAN/HyperGAN
- Stars: 1,183 · Forks: 160
- Language: Python
- License: MIT
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/hypergan-hypergan

## Putting the architecture in a JSON file instead of a class

HyperGAN's central idea is that a generative adversarial network is described by a configuration rather than instantiated by subclassing. The README's About section puts it plainly: HyperGAN builds GANs in PyTorch and makes them easy to train and share. The setup.py description calls it a customizable generative adversarial network with reproducible configurations.

Reproducible is the word doing work there. When the model is a JSON document, a trained model is a file you can diff, review and check into the same repository as the data, and two people can argue about what changed without either of them reading Python. The README's feature list makes the same point from another angle, listing customizable architectures defined in the json alongside the ability to replace any component with your own PyTorch creation.

The templates are managed through the CLI rather than written by hand first. Creating a model from the default configuration is one command, and listing what templates exist is another:

```bash
  hypergan new mymodel
  hypergan new mymodel -l
```

The `-l` flag, also spelled `--list-templates`, is what you want before you commit to a base architecture, since the point of a template system is that several exist. Training then combines a data source, an image shape, a template and a resize flag:

```bash
  hypergan train folder/ -s 32x32x3 -c mymodel --resize
```

Reading that command as documentation tells you the CLI's own grammar: a positional input folder, `-s` for shape, `-c` for the configuration name, and a boolean flag for how images are handled. Those flags are the API surface you will actually use.

## Training and sampling from the command line

The README's first test after install is a preset run against a named dataset, which is the fastest way to find out whether your GPU setup works before you bring your own data into it:

```bash
  hypergan train preset:celeba -s 128x128x3
```

The `preset:` prefix is worth noting. It means the training command accepts a bundled preset as its input in place of a folder, so you can validate the toolchain on known data and only then point it at something of your own.

The fuller training form takes a batch size and a config name, and the sampling command adds a sampler and a save flag:

```bash
  hypergan sample [folder] -s 32x32x3 -b 32 --config [name] --sampler batch_walk --save_samples
```

By default hypergan does not write training samples to disk, and `--save_samples` changes that. For a GAN, that default is sensible, since a training run can emit a very large number of intermediate images, and it is worth knowing before you point it at a long run and fill a disk.

Two operational details the README is unusually direct about. You can move the backend to CPU with `hypergan [...] -B cpu`, followed immediately by the advice not to train on CPU because it is too slow. And `hypergan -h` prints the full argument list, which is what you want given how many flags the training and sampling commands accumulate. The troubleshooting section points at cuda, Nvidia drivers, pillow, PyTorch and torchvision versions being current, which tells you the dependency stack is expected to move.

## The Python API is the smaller half of the story

HyperGAN is usable as a library, and the README gives three snippets that between them cover the whole surface. Loading a trained model and sampling from it:

```python
my_gan = hg.GAN('model.hypergan')
batch_sample = my_gan.sample()
```

Building and training one programmatically:

```python
gan = hg.GAN("default.json", inputs=hg.inputs.ImageLoader(...))
trainable_gan = hg.TrainableGAN(gan)
for step in trainable_gan.train():
    print("I'm on step ", step)
```

The split between `GAN` and `TrainableGAN` is the interesting design decision. A plain `GAN` is a thing you can sample from, and wrapping it in `TrainableGAN` is what turns it into something that yields steps while it trains. That separation means inference code and training code do not have to share an object, and it is the reason a trained model can be a single file, since everything needed to sample is in the config and the weights.

The README flags the API's own maturity, saying the API is currently under work in 1.0 and that anyone reading before 1.0 is released should check the examples. Since 1.0 was never formally released, treat that caveat as permanent. The package is imported as `hypergan as hg`, and the version is unpinned in the way you would expect from a framework that expects you to control your PyTorch version.

## Dependencies, packaging, and a project split across two URLs

requirements.txt is short and reveals the architecture: hyperchamber pinned to 0.3.1, inflection, numpy, pillow, psutil, pyparsing, torch, torchvision and semantic_version. Only one of those is pinned, which is the norm for a framework that expects to share a torch install with your other work, but it also means a fresh environment resolves torch independently of anything HyperGAN was tested against.

The packaging story has one wrinkle worth checking before you install from PyPI. setup.py declares version 1.0.6, while the repository's newest GitHub release is 1.0.0-rc2, published 2020-08-09, preceded by 1.0.0-rc1 a week earlier and 0.10.1 in July 2019. So the pip package version and the release tags have drifted apart, and the README still describes the project as pre-release and open beta. Setup itself is old-fashioned, using distutils and setuptools with glob-based subpackage discovery, and there is a `bin/` directory and a deploy.sh alongside it.

For local development the README's development mode is a clone followed by an editable install:

```bash
git clone https://github.com/hypergan/hypergan
cd hypergan
python3 setup.py develop
```

Note that it also tells you to uninstall any pip copy first to avoid version conflicts, which is sensible advice for a project where two copies of the same importable package will otherwise silently shadow each other. One documentation detail: setup.py's url field points at the 255BITS organisation while the README's clone instructions and examples link point at the hypergan organisation. Both appear in the repository, so follow the README for the clone.

## Datasets, unclean data, and what the feature list promises

The dataset model is deliberately low friction. The README says datasets are meant to be simple to create and that you just use a folder of images, with nested folders working too. It also claims HyperGAN is built to be resilient to all types of unclean data, and states the default behaviour: images are resized then cropped if necessary.

That default is worth understanding rather than accepting. If your images have inconsistent aspect ratios, a resize-then-crop pipeline will silently crop content, and for anything where composition matters that is a modelling decision, not a convenience. The README points at `--nocrop`, `--random_crop` and `--resize` for the alternatives, so the behaviour is adjustable rather than fixed.

The 1.0 feature list is broader than the tooling supports today, and reading it as a specification is the fastest way to be disappointed. It promises an API, a CLI, an Electron viewer app, cross-platform support, inference, accelerated parallel training backends, sharing as hypergan or onnx models, custom architectures, unsupervised learning, unsupervised alignment, transfer learning and online learning. Several of these are load-bearing claims, particularly sharing as onnx models and unsupervised alignment between two distributions, because they imply capabilities beyond what the CLI snippets demonstrate.

The topics list adds one word that the feature list also carries: online learning, alongside unsupervised-learning and pytorch. That combination, online and unsupervised, is a rarer research direction than ordinary supervised GAN work, and it is where you would look first if you came to HyperGAN specifically for that rather than for the JSON configuration convenience.

## Conclusion

HyperGAN is worth a look if you want a GAN whose architecture is a data file you can commit to a repository and diff, rather than a class you have to import, and if you are comfortable working in PyTorch directly. The JSON configuration model is the real contribution and it survives the project's age. What does not survive as well is the release history: the newest tagged release is 1.0.0-rc2 from 2020-08-09 while setup.py declares version 1.0.6, so the pip package and the release tags disagree, and the README still calls the project pre-release and open beta. If you adopt it, pin an exact version, expect to read the gitbook rather than the README for anything beyond the quick start, and confirm that whatever PyTorch version you run works with the code rather than assuming the unpinned torch requirement in requirements.txt resolves to something compatible.

## FAQ

### What is HyperGAN?

HyperGAN is a composable GAN framework for developers, researchers and artists, written in Python on top of PyTorch. Its distinguishing feature is that a network's architecture is described in a JSON configuration file, which makes models reproducible and shareable as files rather than as code.

### How do I train a HyperGAN model on my own images?

Point the training command at a folder of images, give it a shape, a configuration template and a resize flag, for example `hypergan train folder/ -s 32x32x3 -c mymodel --resize`. By default images are resized then cropped if necessary, and `--nocrop` or `--random_crop` change that behaviour.

### Can I use HyperGAN from Python instead of the command line?

Yes. Load an existing model with `hg.GAN('model.hypergan')` and call `sample()`, or build one with `hg.GAN("default.json", inputs=hg.inputs.ImageLoader(...))` and wrap it in `hg.TrainableGAN(gan)` to iterate over training steps. The README notes this API was still under work in 1.0 and suggests checking the examples.

### What is the latest HyperGAN release, and is it production ready?

The newest GitHub release is 1.0.0-rc2, published 2020-08-09, while setup.py declares version 1.0.6, so the pip version and the release tags do not line up. The README describes the project as pre-release and open beta, and the last push on the repository was on 2026-09-20.

### What licence is HyperGAN under?

MIT. setup.py sets the licence field to MIT and the repository carries a LICENSE file at its root.

## Sources

- [HyperGAN/HyperGAN on GitHub](https://github.com/HyperGAN/HyperGAN)
- [Issues](https://github.com/HyperGAN/HyperGAN/issues)
- [License: MIT](https://github.com/HyperGAN/HyperGAN/blob/master/LICENSE)
- [README](https://github.com/HyperGAN/HyperGAN/blob/master/README.md)
- [Releases](https://github.com/HyperGAN/HyperGAN/releases)

---

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