LyCORIS: parameter-efficient fine-tuning for Stable Diffusion beyond plain LoRA

What LyCORIS actually solves, and who it is for

LoRA made adapter training cheap, but it also fixed a shape: two low-rank matrices multiplied together, applied to a linear layer. LyCORIS exists because that shape is not always the right one. The project describes itself as implementing "different parameter-efficient fine-tuning algorithms for Stable Diffusion," and it grew out of LoCon, which the README points to on an archive branch. The current algorithm list is LoRA (LoCon), LoHa, LoKr, (IA)^3, DyLoRA and native fine-tuning, with GLoRA and GLoKr listed as coming soon.

The audience is narrow and specific. This is a library for people who train adapters, not for people who download them. If you fine-tune on a single consumer GPU and you have hit the ceiling of what plain LoRA gives you at a fixed parameter budget, the alternatives here are the point. LoHa and LoKr change the decomposition itself rather than just the rank, and the README's own comparison table frames the trade-off as fidelity against flexibility against diversity against size. That table carries an explicit caveat: "to be taken with a grain of salt," and the project adds that actual performance varies with datasets, tasks and hyperparameters. Treat the star ratings as a map of the design space, not as measurements.

The secondary audience is tool authors. LyCORIS doubles as a set of standalone wrappers for any PyTorch module, which is a different product from the Stable Diffusion trainer sharing the same repository.

LoHa, LoKr and (IA)^3: how the decompositions differ

The mechanism that separates these algorithms is where the low-rank structure is inserted and how many parameters it costs. LoRA keeps the familiar pair of matrices. LoHa uses a Hadamard product of two low-rank pairs, which raises the effective rank of the update without raising the parameter count in the same proportion. LoKr goes further and factorises the weight update itself into Kronecker products, with a factor parameter that controls the split.

The factor is the knob that matters most in practice, and the README gives concrete guidance rather than leaving it abstract. It defines low factor as `factor <= 0.5 * sqrt(dim)` and high factor as `factor >= sqrt(dim)`, then anchors that to real models: factor at or below 8 is low factor for SD1.x, SD2.x and SDXL, and factor at or above 16 is high factor. The table shows LoKr at low factor scoring highest on fidelity and training speed for both linear and convolutional layers, while losing on flexibility. High factor flips it, gaining diversity and shrinking size but dropping fidelity, and the README adds a footnote that switching base model or combining multiple concepts may become harder in that configuration.

(IA)^3 is the outlier. It does not decompose weights at all; it learns per-channel rescaling vectors. That makes it extremely small and very fast to train, and it is the natural choice when you want to shift the style or the overall behaviour of a model rather than teach it a new subject. DyLoRA is a different kind of outlier: it trains a LoRA whose rank can be truncated at inference time, so one checkpoint covers several rank budgets. The README lists it among the implemented algorithms but the documentation for its training arguments lives in the network-args page rather than in the README body.

Installing lycoris-lora and running a first training job

The package is on PyPI as `lycoris-lora` and requires Python 3.10 or newer according to pyproject.toml. The README gives two install paths, pip and source. Both assume you are inside the virtual environment of whatever training front end you use, which the README states explicitly.

pip install lycoris-lora

That pulls torch, einops, toml, tqdm, numpy and safetensors. The fused kernels are a separate optional extra, and pyproject.toml notes in a comment that "without them everything falls back to torch." If you want them, the extra is named `kernels` and resolves to triton on Linux, triton-windows on Windows and tilelang. Installing the extra is not required to train.

For a first real run, the supported path is kohya-ss/sd-scripts. You point its `train_network.py` at the LyCORIS network module instead of the built-in LoRA one, and pass the algorithm through `network_args`. The README's command-line example looks like this:

accelerate launch train_network.py \
  --network_module lycoris.kohya \
  --network_dim "DIM_FOR_LINEAR" --network_alpha "ALPHA_FOR_LINEAR"\
  --network_args "conv_dim=DIM_FOR_CONV" "conv_alpha=ALPHA_FOR_CONV" \
  "dropout=DROPOUT_RATE" "algo=locon" \

The placeholders are the README's own; you replace them with integers. Note that `conv_dim` and `conv_alpha` are separate from the linear pair, which is the LoCon inheritance showing through, and that `algo` selects the algorithm. The README does not enumerate the accepted values of `algo` in this snippet, so check the network-args document before assuming a spelling.

There is also a config-file path, which is easier to keep under version control than a long command line:

accelerate launch train_network.py \
  --config_file example_configs/training_configs/kohya/loha_config.toml \
  --dataset_config example_configs/training_configs/kohya/dataset_config.toml

The repository ships example TOML files under `example_configs/training_configs/kohya`, including a LoHa config, and a parallel set of YAML files under the hcp directory. Read the TOML before your first run; it is the fastest way to see which keys the kohya module accepts.

Where the training-to-inference handoff breaks

The awkward part of LyCORIS is not training. It is getting the result into the interface you actually generate with. For a1111/sd-webui the story is clean: from 1.5.0 onward LyCORIS models are supported by the built-in LoRA system, you drop the file into `models/Lora` or `models/LyCORIS`, and you trigger it with the standard `<lora:filename:multiplier>` syntax. The README commits to keeping new model types working with the newest sd-webui, which is a maintenance promise worth noting given how often that project's loader changes.

Older sd-webui and sd-webui-forge are not covered by that promise. They need the separate `a1111-sd-webui-lycoris` extension. ComfyUI, InvokeAI, CivitAI and Tensor.Art are listed as supporting LyCORIS models, but the README is candid that this is a best-effort list and asks readers to help complete it. The sentence that matters most is this one: "newer model types may not always be supported." If you train a LoKr today, there is no guarantee the site or node you upload to will parse it. The README's suggested remedy is to ask the maintainers of that interface to add support, which is not a remedy you control.

HCP-Diffusion is the clearest failure case. Support was dropped in LyCORIS 3.0.0, and the README says the project will wait until HCP finishes implementing the new wrapper. The HCP example command is still printed, but the surrounding text makes the status plain. Worse, the README states that HCP-Diffusion outputs are not directly compatible with a1111/sdwebui and require a conversion pass through `tools/batch_hcp_convert.py`. Bundle formats need a further step through `tools/batch_bundle_convert.py`. Two conversion scripts between training and generation is a real cost, and it is the kind of thing that silently corrupts a checkpoint if you skip it.

The standalone wrapper API, and when it is the wrong tool

Away from Stable Diffusion, LyCORIS exposes `create_lycoris` and `LycorisNetwork` from the `lycoris` package, and the README points to `example/standalone_example.py` for a full example. The repository also carries `example/bnb_example.py`, `example/functional_example.py`, `example/high_precision_merge_demo.py` and `example/stacked_wrapper_demo.py`. The file names alone tell you the intended reach: quantised base models, functional-style injection, merging at higher precision, and stacking multiple adapters. The README's phrasing is that LyCORIS works as standalone wrappers for "ANY" pytorch modules, with the capitals in the original.

That breadth is also where the library stops being the right answer. Three cases stand out.

First, if you only generate images, you do not need this package. The built-in loader handles the files. Installing the training library to run inference adds torch-version surface area for nothing.

Second, if plain LoRA already meets your fidelity target, the extra algorithms buy you a different point on a trade-off curve, not a free improvement. The README's own table shows LoKr at high factor scoring worst on fidelity among the listed methods. Choosing it for a subject that needs precise likeness is a mistake the table already warns about.

Third, if your front end is not on the supported list, you are writing the integration yourself. The kohya module and the HCP module are the two shipped integrations, and one of them is explicitly paused. There is no generic plugin layer for other trainers.

Alternatives: what kohya-ss/sd-scripts and plain LoRA do differently

The most direct alternative is the LoRA implementation built into kohya-ss/sd-scripts. It is not a competitor in the sense of a separate product; it is the same training script LyCORIS plugs into, with its own network module. The difference is scope. The built-in module implements conventional LoRA, with the linear and convolutional rank arguments you would expect. LyCORIS replaces that module and adds LoHa, LoKr, (IA)^3 and DyLoRA behind the same `--network_args` interface. If you never change `algo` away from LoRA, you are running roughly the same thing through a different code path, and the built-in module is one fewer dependency to keep in step with your torch build.

The second alternative is full fine-tuning, which LyCORIS also implements and the README calls native fine-tuning, or dreambooth. Full fine-tuning sits at the top of the README's fidelity column and the bottom of its size column. It produces a complete model rather than an adapter, which means no loading syntax, no multiplier, and no compatibility question about whether a website parses your file. The cost is storage and the loss of the ability to stack or blend several concepts by filename. LyCORIS's entire value proposition is the space between those two poles: adapters that behave more like full fine-tuning than LoRA does, at adapter sizes.

The third alternative, for the standalone use case, is writing the low-rank wrapper yourself. It is a small amount of code for plain LoRA. It stops being small once you want Kronecker factorisation or per-channel rescaling with the same save and load semantics, which is what the `example/` directory is demonstrating.

Maintenance, licensing and the upgrade cost

The repository is not archived, and the last push was on 2026-09-05, which is recent. The release history shows v4.0.0 on 2026-09-01 followed by two development builds, v4.0.1.dev20260902072855 and v4.0.1.dev20260905071546. Those dev version strings embed a timestamp, so the project tags intermediate states rather than only stable releases. pyproject.toml declares version 4.0.0 while the newest release tag is a 4.0.1 dev build, which is worth knowing if you pin by version and wonder why pip resolves something the manifest does not mention.

The upgrade cost is concentrated in two places. The first is the algorithm list itself: HCP-Diffusion support was removed at 3.0.0, so anyone whose pipeline depended on the `lycoris.hcp` module has already had to migrate or pin. The second is the inference side, where support depends on third parties. A new algorithm can be trainable in LyCORIS and unreadable in ComfyUI or on a hosting site on the same day. Planning a workflow around a brand-new algorithm means accepting that gap.

Licensing is Apache-2.0, declared both in pyproject.toml and in the repository's LICENSE.md. That is a permissive licence with an explicit patent grant and a requirement to preserve notices, and it is compatible with the ecosystem this library plugs into. This is a description of the licence text, not legal advice; if you are shipping a product that bundles the library, read LICENSE.md and the terms of the base models you fine-tune separately, because the model weights carry their own licences that LyCORIS does not address.

Editorial conclusion

Adopt LyCORIS if you train adapters for Stable Diffusion and want LoHa, LoKr or (IA)^3 alongside plain LoRA, or if you need to wrap arbitrary PyTorch modules with the standalone API. Do not adopt it if you only generate images: the built-in LoRA loader in sd-webui 1.5.0 and later already reads LyCORIS files, so the library adds nothing to an inference-only workflow. Before committing, verify that your training front end is on the supported list (kohya-ss/sd-scripts or Naifu-Diffusion; HCP-Diffusion support was dropped in LyCORIS 3.0.0), check that your interface can load the specific algorithm you intend to train, since the README warns that newer model types may not always be supported, and confirm that the optional kernels extra is worth installing on your platform, because without it the documentation states everything falls back to torch.

Frequently asked questions

Official sources

1. Issues
2. KohakuBlueleaf/LyCORIS on GitHub
3. License: Apache-2.0
4. README
5. Releases