# Lumina-Image 2.0 puts a 2.6B text to image model and its training code in one repository

> Lumina-Image 2.0 is an Apache-2.0 image generation framework from Alpha-VLLM that ships a 2.6B checkpoint, a Gradio demo, a fine-tuning script and a Diffusers pipeline, with a Gemma-2-2B text encoder and a 1024 pixel target. It suits teams that want to fine tune or self host an open image model, and it is a poor fit for anyone who needs a turnkey hosted endpoint.

**Alpha-VLLM/Lumina-Image-2.0** — Lumina-Image 2.0: A Unified and Efficient Image Generative Framework

- Repository: https://github.com/Alpha-VLLM/Lumina-Image-2.0
- Website: https://arxiv.org/abs/2503.21758
- Stars: 903 · Forks: 65
- Language: Python
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/alpha-vllm-lumina-image-2-0

## One model, two text encoders' worth of moving parts

The model zoo table in the project lists a single configuration: a 1024 resolution model with 2.6B parameters, a Gemma-2-2B text encoder, and the FLUX-VAE-16CH VAE, with the weights hosted on Hugging Face. That combination matters for adoption. The parameter count describes the diffusion model itself, while the text encoder and the VAE are separate components that you have to fetch and that the license terms of Gemma apply to separately from the Apache-2.0 license on this repository.

The architecture of the repository matches that decomposition. There is a models directory, a transport directory, a util directory and a data directory, alongside finetune.py, sample.py, demo.py, imgproc.py, parallel.py and grad_norm.py at the root. The requirements file is short and telling: diffusers, fairscale, accelerate, tensorboard, transformers, gradio, torchdiffeq, click and torchvision. torchdiffeq is the continuous ordinary differential equation solver package, which lines up with the sampler choices the project advertises.

Researchers at the University of Sydney, Shanghai AI Laboratory, Shanghai Innovation Institute, the Chinese University of Hong Kong and Shanghai Jiao Tong University are credited on the project page.

## Sampling comes in three solver flavours

The inference side supports multiple solvers, and the project names them: the Midpoint Solver, the Euler Solver and the DPM Solver. This is the main axis of choice for someone generating images, because the solver and the step count determine how the trajectory from noise to image is integrated.

The Diffusers route offers the standard API surface. The pipeline is loaded from the repository identifier with bfloat16 weights, and model CPU offloading is offered as a way to trade speed for VRAM.

```python
import torch
from diffusers import Lumina2Pipeline

pipe = Lumina2Pipeline.from_pretrained("Alpha-VLLM/Lumina-Image-2.0", torch_dtype=torch.bfloat16)
pipe.enable_model_cpu_offload() #save some VRAM by offloading the model to CPU. Remove this if you have enough GPU power
```

The in repository route runs through sample.py instead, driven by a shell script. Two arguments matter there. The --model_dir flag takes either a local checkpoint directory or the identifier Alpha-VLLM/Lumina-Image-2.0, and --cap_dir points at a caption source, which can be a JSON file containing a prompt field or a plain text file with one prompt per line.

```bash
bash scripts/sample.sh
```

That distinction is the real choice between the two paths. Diffusers gives you a familiar pipeline object with model offloading and device handling. The native script gives you direct control over the solver and over batch caption input, at the cost of writing your own surrounding code.

## Setting up the environment the fine tuning path expects

The documented setup starts from a conda environment on Python 3.11.

```bash
git clone https://github.com/Alpha-VLLM/Lumina-Image-2.0.git
conda create -n Lumina2 python=3.11 -y
conda activate Lumina2
```

Dependencies come from the requirements file, plus a flash-attention build.

```bash
cd Lumina-Image-2.0
pip install -r requirements.txt
pip install https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.2cxx11abiFALSE-cp311-cp311-linux_x86_64.whl --no-build-isolation
```

That wheel URL is the first hard constraint. It encodes CUDA 12, torch 2.2, CPython 3.11 and Linux on x86_64, so the documented path assumes that combination. The project acknowledges this by pointing readers to the flash-attention releases page to find a matching wheel, but no guidance is given for macOS or for a different torch version.

Training data is declared in configs/data.yaml as a list of links to your data files, and each image text pair uses a simple shape.

```json
{
    "image_path": "path/to/your/image",
    "prompt": "a description of the image"
}
```

The run script is then started with a single command, and the token is passed through an argument rather than an environment variable.

```bash
bash scripts/run_1024_finetune.sh
```

The Gemma-2-2B encoder is gated, so the token is required for the fine tuning path. The project notes this explicitly and points to the Hugging Face access token settings page.

## The Gradio demo is a separate entry point with its own port

The web demo is demo.py, and it takes its own arguments: the checkpoint path, the resolution, the port and the token.

```python
python demo.py \
    --ckpt /path/to/your/ckpt \
    --res 1024 \
    --port 10010 \
    --hf_token xxx
```

The default port in the documented invocation is 10010, and the same number appears in the published demo address listed on the project page. If you intend to run the demo on a shared host, change the port before exposing it.

The checkpoint argument accepts either a local directory or a download location. The project states that the .pth weight files have been uploaded to Hugging Face, and that the --ckpt argument can simply be pointed at that download directory.

Two other routes exist for running the model without touching the Python code. ComfyUI support was added in February 2025 through a repackaged workflow, and the Diffusers team published a LoRA fine tuning script for Lumina 2.0 in the same month. The project page also links an official Hugging Face Space and a hosted demo. The open source checklist on that page marks inference, checkpoints, the web demo, fine tuning code, ComfyUI, Diffusers, LoRA and control as done, with PEFT under the LLaMa-Adapter V2 name still unchecked.

## The gap between the release history and the commit history

The repository has no GitHub releases at all. Version tracking happens elsewhere, through the Hugging Face checkpoint files and through the tech report, which was published in March 2025. The last push to the repository was on 2026-05-22.

That combination has practical consequences. There is no tag to pin in a requirements file, no release notes to diff, and no changelog to read before an upgrade. If you depend on this code, the commit hash or the checkpoint revision becomes your unit of reproducibility, and you have to record it yourself.

The research output around the project did keep moving after the first release. The model was accepted at ICCV 2025 in June 2025, and in April 2025 the team released a separate repository called Lumina-Accessory, which handles single task and multi task fine tuning for controllable generation, image editing and identity preservation on top of Lumina-Image 2.0. Earlier entries in the same list cover the Diffusers integration, the Hugging Face Space, the .pth weight upload and the ComfyUI support. A separate repository, Lumina-Video 1.0, holds preliminary video generation work.

The license is Apache-2.0, which is permissive for commercial and research use of the code in this repository. The checkpoint terms for the Gemma-2-2B encoder and the FLUX VAE are set by those projects rather than by this one, and the project does not restate them.

## Where this setup will frustrate you

Three failure modes are visible in the documented flow.

First, the platform surface is narrow. The flash-attention wheel is Linux x86_64 only, the conda environment is pinned to Python 3.11, and the torch version is implied by the wheel rather than stated as a requirement. The requirements file does not pin torch at all, so the torch version your environment resolves can differ from the one the wheel was built against.

Second, the fine tuning path cannot run anonymously. Because the text encoder is gated, a Hugging Face token is a hard requirement rather than an option, and the token has to reach the script through the --hf_token argument, which means it can end up in a shell history or a process listing.

Third, the documentation for the Diffusers route is truncated in the project page. The Python snippet stops partway through the pipe call, so the example you can copy from the page ends before it shows the result being returned. The Diffusers documentation is the place to get the complete call, and the project page points there for pipeline details.

For an evaluation driven by hardware rather than code, none of this is fatal. For a team that expects a stable, versioned artifact, the absence of releases is the bigger problem, because you are tracking a moving branch.

## Conclusion

Adopt Lumina-Image 2.0 if your work involves adapting an open image model rather than just calling one, since the repository carries both the inference entry points and the fine tuning script, and the fine tuning code needs a Hugging Face token for the gated Gemma-2-2B encoder. Do not adopt it if you need a supported service or a release train, because the repository publishes no GitHub releases and the model is distributed through Hugging Face checkpoints instead. Check three things first: that a Python 3.11 environment and a Linux wheel for flash-attention match your hardware, that the checkpoint files you point --ckpt at exist in .pth format, and that the solvers in scripts/sample.sh cover the sampling behaviour you expect.

## FAQ

### What model size and resolution does Lumina-Image 2.0 use?

The model zoo lists a 1024 resolution model with 2.6B parameters, using Gemma-2-2B as the text encoder and the FLUX-VAE-16CH VAE. Weights are distributed through the Hugging Face repository Alpha-VLLM/Lumina-Image-2.0.

### How do I fine tune Lumina-Image 2.0?

The documented path creates a conda environment on Python 3.11, installs requirements.txt plus a flash-attention wheel, lists image text pairs in configs/data.yaml, and runs bash scripts/run_1024_finetune.sh. The Gemma-2-2B encoder is gated, so a Hugging Face access token must be passed with --hf_token.

### Can Lumina-Image 2.0 be used with Diffusers?

Yes. The Lumina2Pipeline class is used with from_pretrained and can offload the model to the CPU to save VRAM. The Diffusers team also published a LoRA fine tuning script for Lumina 2.0.

### Which sampling solvers does Lumina-Image 2.0 support?

The project states that multiple solvers are supported, naming the Midpoint Solver, the Euler Solver and the DPM Solver for inference. The native sample.py entry point is driven by scripts/sample.sh.

## Sources

- [Alpha-VLLM/Lumina-Image-2.0 on GitHub](https://github.com/Alpha-VLLM/Lumina-Image-2.0)
- [Issues](https://github.com/Alpha-VLLM/Lumina-Image-2.0/issues)
- [License: Apache-2.0](https://github.com/Alpha-VLLM/Lumina-Image-2.0/blob/main/LICENSE)
- [Project website](https://arxiv.org/abs/2503.21758)
- [README](https://github.com/Alpha-VLLM/Lumina-Image-2.0/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alpha-vllm-lumina-image-2-0