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.

Project links

Data verified by PyPI on Jul 27, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.1.8)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ljleb from gravatar.com ljleb

Credits

Author: ljleb

GitHub Statistics

Data verified by PyPI on Jul 27, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License

Requires

Python >=3.10

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sd_mecha-1.1.7.tar.gz (161.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

sd_mecha-1.1.7-py3-none-any.whl (181.8 kB view details)

Uploaded Python 3

File details

Details for the file sd_mecha-1.1.7.tar.gz.

File metadata

  • Download URL: sd_mecha-1.1.7.tar.gz
  • Upload date:
  • Size: 161.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for sd_mecha-1.1.7.tar.gz
Algorithm Hash digest
SHA256 2f5eff262882b2b581693580b677065ec8784187bcdc48c255238a40b92ab98a
MD5 6b09a7fcd12a03489f9368e6946a69dd
BLAKE2b-256 fa96af9d1db73a0d5aed97b90778743f43a7239587615c6f7bc99847404652c1

See more details on using hashes here.

Provenance

The following attestation bundles were made for sd_mecha-1.1.7.tar.gz:

Publisher: release.yaml on ljleb/sd-mecha

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sd_mecha-1.1.7-py3-none-any.whl.

File metadata

  • Download URL: sd_mecha-1.1.7-py3-none-any.whl
  • Upload date:
  • Size: 181.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for sd_mecha-1.1.7-py3-none-any.whl
Algorithm Hash digest
SHA256 c7ba3ad7efde7896e7e61c293d645f85033616190c3f966bdf6b892b23ec4461
MD5 df26e0c7d3d6a3b81c667a081ca222d3
BLAKE2b-256 e445b03cf14e6409b7f05e22e8d5ce9e3f80c533c6387a9788c3537ab15815fa

See more details on using hashes here.

Provenance

The following attestation bundles were made for sd_mecha-1.1.7-py3-none-any.whl:

Publisher: release.yaml on ljleb/sd-mecha

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.1.8

2 files

This release

1.1.7 This release

2 files

1.1.6

2 files

1.1.5

2 files

1.1.4

2 files

Yanked

1.1.4rc1

2 files

Yanked reason: only purpose was to test new publishing strategy

1.1.3

2 files

1.1.2

2 files

Yanked

1.1.1

2 files

Yanked

1.1.0

2 files

Pre-release

1.1.0rc3

2 files

Pre-release

1.1.0rc2

2 files

Pre-release

1.1.0rc1

2 files

1.0.14

2 files

1.0.13

2 files

1.0.12

2 files

1.0.11

2 files

1.0.10

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

Yanked

1.0.0

2 files

Yanked reason: rotate does not work

Yanked

0.1.1

2 files

Yanked reason: renamed to 1.0.1

Yanked

0.1.0

2 files

Yanked reason: rotate does not work

Pre-release

0.1.0rc6

2 files

Pre-release

0.1.0rc4

2 files

Pre-release

0.1.0rc3

2 files

Pre-release

0.1.0rc2

2 files

Pre-release

0.1.0rc1

2 files

0.0.29

2 files

Yanked

0.0.28

2 files

Yanked reason: loading empty tensor from state dict raises an error

0.0.27

2 files

0.0.26

2 files

0.0.25

2 files

0.0.24

2 files

0.0.23

2 files

0.0.22

2 files

0.0.20

2 files

0.0.19

2 files

0.0.18

2 files

0.0.17

2 files

0.0.16

2 files

0.0.15

2 files

0.0.14

2 files

0.0.13

2 files

0.0.12

2 files

0.0.11

2 files

0.0.10

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

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