# OminiControl for FLUX Subject and Spatial Control

> OminiControl adds subject-driven and spatial conditioning to FLUX-based diffusion transformers with a small adapter and a reusable generation interface. It suits Python users building controlled image workflows, with strict model and preprocessing requirements.

**Yuanshi9815/OminiControl** — [ICCV 2025 Highlight] OminiControl: Minimal and Universal Control for Diffusion Transformer

- Repository: https://github.com/Yuanshi9815/OminiControl
- Stars: 1,958 · Forks: 151
- Language: Python
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/yuanshi9815-ominicontrol

## OminiControl's Subject and Spatial Control Scope

OminiControl is a Python framework for adding controllable conditioning to diffusion transformer models such as FLUX. It addresses two related needs. Subject-driven control uses a reference image to place a recognizable object in a generated scene. Spatial control uses a condition image to guide an output, with examples covering Canny edges, depth, colorization, deblurring, and inpainting.

The likely audience is engineers and researchers who need controllable image generation while retaining a FLUX-based pipeline. The repository presents its first uses as Jupyter notebooks rather than a standalone CLI application. That makes it suitable for model experimentation, internal tooling, and reproducible research workflows where Python code and GPU-based inference are already acceptable.

OminiControl is not documented as a general-purpose image editor. Its scope is conditioning and controlled generation. The training directory can be used to create models for additional tasks such as 3D, multi-view, pose-guided generation, and try-on, but the existence of training code does not mean that pretrained checkpoints or complete datasets are supplied for every listed task. Each custom control task requires the relevant data, training configuration, and validation.

One important content boundary is subject type. The README says the model primarily works with objects rather than human subjects because its training data did not include humans. This makes OminiControl less suitable for portrait identity, face consistency, or human try-on unless a separately trained model and suitable data address that gap.

## OminiControl Adapter Architecture and Condition Flow

OminiControl preserves the original diffusion transformer structure and injects control signals through a small addition to the base model. The README states that the method introduces approximately 0.1% additional parameters. The repository layout supports that design: reusable Python implementation code is under `omini/`, example notebooks are under `examples/`, and model creation and training resources are under `train/`.

The documented generation function accepts a pipeline, a text prompt, one or more condition images, and an optional strength value. The condition-strength interface is `condition_scale`, with a default of `1.0`. According to the README, values above `1` strengthen the condition image's influence, values below `1` weaken it, and `0` suppresses the condition entirely.

This design gives callers a direct control without requiring a separate generation function for each condition strength. It also exposes an important practical choice: object fidelity and prompt adherence may compete as conditioning becomes stronger. The README describes the direction of the effect but does not provide a task-specific recommendation for selecting a value.

OminiControl2 introduces a distinct conditioning path for efficient inference. With `kv_cache=True`, the condition branch's keys and values are computed once and reused during the remaining diffusion steps. The README reports an approximately 1.5x end-to-end speedup at 8 steps. This is a stated project result, not an independent verification. Cache use requires a LoRA trained with `independent_condition: true`, so it cannot be assumed to work with every OminiControl adapter.

## Installing OminiControl with Python, Torch, and CUDA

The README documents a Python 3.12 environment and a separately installed Torch wheel. The Torch wheel index must match the CUDA environment used by the reader. First create and activate the Conda environment:

```bash
conda create -n omini python=3.12
conda activate omini
```

The documented installation for a CUDA 12.8 wheel is:

```bash
pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu128
```

The README says to choose the index URL matching the selected CUDA version. The repository does not provide commands for every CUDA version, so readers using another configuration must map their environment to the corresponding official PyTorch wheel index without assuming that the shown URL is universal.

After installing Torch, install the Python dependencies from the repository root:

```bash
pip install -r requirements.txt
```

`requirements.txt` identifies the validated stack as Python 3.12, Torch 2.8 with CUDA 12.x wheels, and `diffusers` 0.38.0. It pins `diffusers==0.38.0`, allows `transformers>=4.55,<5`, and requires `huggingface_hub<1.0`. The comment in that file says a `huggingface_hub` version of 1.0 or later breaks `import transformers` in the documented environment.

The repository does not document minimum GPU memory, CPU support, container images, or a complete hardware matrix. Those omissions matter for an image diffusion framework because installation can succeed even when inference later fails because of hardware limits.

## First OminiControl Subject Generation Workflow

The documented starting point for subject control is `examples/subject.ipynb`. For `FLUX.1-dev`, the README points to `examples/subject_dev.ipynb`. For 1024x1024 output, it points to `examples/subject_1024.ipynb` and states that this notebook uses the 1024-trained model for the best quality.

Open the selected notebook inside the `omini` environment. The repository does not provide a standalone command for subject generation, so the notebook remains the authoritative setup for loading its pipeline, checkpoint, and helper functions. Before generation, the input image must be center-cropped and resized to the selected model's native resolution. The pipeline does not perform this preprocessing automatically.

The README specifies 512x512 for `subject` and `subject_512`, and 1024x1024 for `subject_1024_beta`. These model names are significant because the native resolution changes with the checkpoint. Passing an arbitrary image size without the documented preprocessing can move the request outside the conditions under which the example was prepared.

After pipeline initialization, the README gives this condition-strength example:

```python
result = generate(pipe, prompt=prompt, conditions=[condition], condition_scale=1.3)
```

At `1.3`, the condition image has more influence than the documented default of `1.0`. Prompts should refer to the reference using phrases such as `this item`, `the object`, or `it`. This wording aligns the prompt with the subject-conditioning interface, although it does not guarantee that an object will remain visually exact.

## OminiControl Spatial Tasks and Adapter Selection

The `examples/spatial.ipynb` notebook combines several condition types: Canny edge to image, depth to image, colorization, and deblurring. `examples/inpainting.ipynb` covers masked image completion, while `examples/ominicontrol_art.ipynb` documents the OminiControl Art stylization workflow.

OminiControl can also be combined with a custom style LoRA. The relevant notebook is `examples/combine_with_style_lora.ipynb`. Its adapter activation behavior introduces a concrete integration issue. When several adapters are loaded through repeated `pipe.load_lora_weights(..., adapter_name=...)` calls, only the last loaded adapter stays active unless adapters are selected explicitly.

The README supplies this activation pattern:

```python
pipe.set_adapters(["adapter_a", "adapter_b"])
```

This is not merely a style recommendation. Without explicit activation, a workflow may load multiple adapters while producing output that reflects only one of them. Developers integrating more than one LoRA should therefore inspect the adapter names in their notebook and confirm that `set_adapters()` lists every adapter intended for that generation.

The training directory broadens the possible control set, but each task still has a separate implementation cost. The README names 3D, multi-view, pose-guided generation, and try-on as examples. It does not document ready-made checkpoints, training duration, training data licensing, or expected quality for these tasks, so the presence of extensible training code should not be treated as an adoption guarantee.

## OminiControl2 KV-Cache Requirements and Failure Modes

OminiControl2's KV-cache option targets repeated diffusion steps, where recomputing condition information adds avoidable work. Passing `kv_cache=True` to `generate()` makes the condition branch compute its keys and values once and reuse them for the remaining steps. The README reports an approximately 1.5x end-to-end speedup at 8 steps.

The compatibility requirement is specific: the LoRA must have been trained with `independent_condition: true`. The README links `train/README.md` for efficient-generation details, but it does not provide the complete training command or dataset preparation steps. A caller using an ordinary OminiControl LoRA cannot assume that the cache path is applicable.

Input preprocessing is another likely failure mode. The README explicitly says that the pipeline does not center-crop or resize subject images. This means the application layer must perform those operations before invoking the pipeline. Ignoring that instruction can produce weak subject preservation or other unexpected results even when the notebook call is otherwise correct.

Human-subject consistency is a separate documented limitation. Because the training data lacked human examples, the current subject model primarily targets objects. Portrait and clothing workflows may require custom training, but the README does not provide evidence that doing so will meet identity or fit requirements. Finally, the KV-cache speedup is tied to eight steps and a compatible LoRA. It should not be generalized to every sampling count, model, adapter, or GPU.

## OminiControl Licensing, Maintenance, and Version Changes

The repository is licensed under Apache-2.0. That license includes permissions and conditions concerning use, modification, and redistribution. Teams using OminiControl in a product should inspect the actual `LICENSE` file and assess their own compliance and notice obligations. This is a technical summary rather than legal advice.

The repository is not archived. Its last push was on 2026-10-02. However, the repository has no GitHub releases, so there is no formal release series or changelog tied to packaged versions. Maintenance activity and release maturity are separate facts here: recent commits do not create a versioned upgrade path.

The README's 2026-07-02 news entry records support for `diffusers` 0.38, the addition of `condition_scale`, subject-driven generation on `FLUX.1-dev`, and documentation for OminiControl2's `kv_cache=True` path. `requirements.txt` also describes its dependency stack as validated in July 2026 and explains the `huggingface_hub<1.0` restriction.

Upgrade work will therefore involve checking notebook expectations, dependency pins, model names, and adapter settings. The README does not provide a formal migration guide, supported-version matrix, or rollback procedure. A local dependency environment that already uses `diffusers` 0.38.0 and `huggingface_hub<1.0` is the best match to the documented stack.

## Conclusion

OminiControl is appropriate for engineers and researchers who need a single FLUX-based interface for subject-driven generation, spatial conditioning, or custom control tasks. It is less suitable for production workflows that depend on consistent human identity, automatic preprocessing, formal releases, or unconfirmed hardware support. The first checks should be Python and CUDA compatibility, the exact checkpoint used by the selected notebook, whether its LoRA supports independent_condition: true when using KV-cache, and whether the required Hugging Face assets are accessible. For object-reference workflows, OminiControl is most directly applicable when callers can center-crop and resize inputs before calling generate().

## FAQ

### How do I install OminiControl for FLUX-based generation?

Create a Python 3.12 Conda environment, install Torch 2.8.0 using the wheel index appropriate for the CUDA version, and then run `pip install -r requirements.txt` from the repository root. The dependency file pins `diffusers==0.38.0` and requires `huggingface_hub<1.0`.

### Can OminiControl control the strength of a condition image?

Yes. Pass `condition_scale` to `generate()`. Its default is `1.0`, values above `1` strengthen the condition image's influence, values below `1` weaken it, and `0` suppresses it.

### Does OminiControl support subject generation with FLUX.1-dev?

Yes. The README points to `examples/subject_dev.ipynb` for subject-driven generation on `FLUX.1-dev`. It also requires the input image to be center-cropped and resized to the model's native resolution before use.

### Can OminiControl KV-cache inference work with every LoRA?

No. The README says `kv_cache=True` requires a LoRA trained with `independent_condition: true`. In that configuration, the condition branch's keys and values are computed once and reused during later steps.

### What subjects does the documented OminiControl model handle well?

The README says the current subject-driven model primarily works with objects rather than human subjects because its training data did not include humans. Human identity and portrait consistency are not documented capabilities.

## Sources

- [Issues](https://github.com/Yuanshi9815/OminiControl/issues)
- [License: Apache-2.0](https://github.com/Yuanshi9815/OminiControl/blob/main/LICENSE)
- [README](https://github.com/Yuanshi9815/OminiControl/blob/main/README.md)
- [Yuanshi9815/OminiControl on GitHub](https://github.com/Yuanshi9815/OminiControl)

---

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