Skip to main content

sd-mecha

PyPI version Discord Server

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:

image of typical merge graph

sd-mecha doesn't have this problem as it saves keys as soon as it can:

image of sd-mecha merge graph

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)

Source distribution for sd-mecha 1.1.8
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)

Table of built distributions (wheels) for sd-mecha 1.1.8
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

1.1.8 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page