sd-mecha
import sd_mecha
# create the merge plan
a = sd_mecha.model("path/to/model_a.safetensors")
b = sd_mecha.model("path/to/model_b.safetensors")
recipe = sd_mecha.weighted_sum(a, b, alpha=0.5)
# merge!
sd_mecha.merge(recipe, output="path/to/model_out.safetensors")
sd-mecha is a general memory-efficient model merging library. It can merge any model:
- Diffusion models
- LLMs
- VLMs
- Aesthetic scorers
- etc.
Features
- Memory efficient model merging: merge a very large number of models in a single execution
- Textual and interpretable format for storage and execution (.mecha)
- Extensible library interface:
- add custom models
- add custom merge methods
- Builtin support for popular diffusion models:
- Stable Diffusion 1.5
- Stable Diffusion XL
- Stable Diffusion 3
- FLUX Schnell/Dev
- Merge LyCORIS networks together and to checkpoints
- Block-wise hyperparameters for precise control of blocks (aka MBW)
Install
pip install sd-mecha
Make sure to install the appropriate release of torch to get the best performance.
Usage
Merge models
To merge models, mecha uses recipes. A recipe is a list of instructions that describes the exact steps needed to derive a state dict from inputs.
Here's an example script that merges three models:
import sd_mecha
# create the merge plan
model_a = sd_mecha.model("path/to/model_a.safetensors")
model_b = sd_mecha.model("path/to/model_b.safetensors")
recipe = sd_mecha.weighted_sum(model_a, model_b, alpha=0.5)
# merge!
sd_mecha.merge(recipe, output="path/to/model_out.safetensors")
See the examples directory for more examples.
Get Model-Specific Information
The library uses a "model config" to designate any specific set of keys of a certain shape.
It is possible to list all available model configs through the sd_mecha.extensions.model_configs module:
from sd_mecha.extensions import model_configs
all_configs = model_configs.get_all()
print([config.identifier for config in all_configs])
# ["sd1-ldm-base", "sdxl-sgm-base", "sd3-sgm-base", ...]
A component of a model config is a subset of keys of the config that belong to the same logical group. For example, all keys starting with "first_stage_model." in Stable Diffusion models belong to the component "vae".
It is possible to query the different components of a model config:
from sd_mecha.extensions import model_configs
config = model_configs.resolve("sd1-ldm")
for component_id, component in config.components().items():
# component.keys contains the state dict keys that the component owns
print(f"{component_id}")
# this prints:
# clip_l
# vae
# diffuser
Motivation
Keeping track of full merge recipes has always been a problem for me. I needed something that allows to store merge recipes in a readable format while also being executable. I also needed something that allows to fully merge an entire tree of models without having to save intermediate models to disk.
Typically, mergers load all models in memory before initiating the merge process. This can be very inefficient when the merge focuses on each key individually:
sd-mecha doesn't have this problem as it saves keys as soon as it can:
This allows to merge a very large number of models simultaneously on low-end hardware.
Metadata
Release files for sd-mecha 1.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sd_mecha-1.1.8.tar.gz | 161.5 kB | With provenance | Details for sd_mecha-1.1.8.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sd_mecha-1.1.8-py3-none-any.whl | Python 3 | none | any | Details for sd_mecha-1.1.8-py3-none-any.whl |
Total release size: 343.3 kB
Release files / sd_mecha-1.1.8.tar.gz
| Download URL | sd_mecha-1.1.8.tar.gz |
|---|---|
| Size | 161.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
523881fc75f96e90b18274c8ef35c3168fe5fe41927d6034758a4b650993b199
|
|
BLAKE2b-256 checksum How to use checksums |
bf956dedff11d546115222e93137f975790510a1e0bbe5a57cdb4c659b0d4e9c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / sd_mecha-1.1.8-py3-none-any.whl
| Download URL | sd_mecha-1.1.8-py3-none-any.whl |
|---|---|
| Size | 181.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a1ea018fc479d3f1abf7c21ab7aded2a90c575b083074fd2767516df59b3612
|
|
BLAKE2b-256 checksum How to use checksums |
e90ffb47c5044ae1c9fcbefd1eed10ab7970eea688cdeaaa15309793012856be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logSecurity for sd-mecha 1.1.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sd_mecha-1.1.8.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.