Copyright 2025-2026 Ardan Labs
This project lets you use Go for hardware accelerated local image and video generation with stable-diffusion.cpp directly integrated into your applications. Malina maps the safe public stable-diffusion.h API plus pure-Go PNG/JPEG I/O and Motion-JPEG AVI muxing.
Malina is the image-generation sibling of ardanlabs/bucky (which binds whisper.cpp) and hybridgroup/yzma (which binds llama.cpp). The end goal is to give Kronk a native, OpenAI-compatible POST /v1/images/generations endpoint without the CGo toolchain.
Malina is the Russian word for "raspberry" — a small, dense, fast-growing fruit. Naming a stable-diffusion binding after a fast little thing that sprouts colorful pictures is just good taste.
To install malina, fetch the stable-diffusion.cpp shared libraries, and generate the bundled cat sample:
$ go install github.com/ardanlabs/malina@latest
$ malina install -u
$ malina model pull sd-1.5
$ go run ./examples/hello "a lovely cat"Sometimes there are breaking changes to stable-diffusion.cpp that require an update to malina. Here are the known compatible versions:
| stable-diffusion.cpp | malina | Linux prebuilt requirements |
|---|---|---|
| master-1106-532d2c1 | 1.2.3 | CPU/Vulkan: Ubuntu 26.04 (glibc ≥2.43); ROCm archive: Ubuntu 24.04 |
| master-1088-32d516c | 1.2.2 | CPU/Vulkan: Ubuntu 26.04 (glibc ≥2.43); ROCm archive: Ubuntu 24.04 |
| master-1088-32d516c | 1.2.1 | CPU/Vulkan: Ubuntu 26.04 (glibc ≥2.43); ROCm archive: Ubuntu 24.04 |
| master-1052-f5df5f8 | 1.2.0 | CPU/Vulkan: Ubuntu 26.04 (glibc ≥2.43); ROCm archive: Ubuntu 24.04 |
Malina 1.2.3 requires the new opaque-options/tensor/result C API. Its native library is not interchangeable with the struct-based API used by 1.2.2 and earlier. Upgrade Malina and its verified libraries together:
$ go install github.com/ardanlabs/malina@v1.2.3
$ malina install -u -lib ./libName: Bill Kennedy
Company: Ardan Labs
Title: Managing Partner
Email: bill@ardanlabs.com
BlueSky: https://bsky.app/profile/goinggo.net
LinkedIn: www.linkedin.com/in/william-kennedy-5b318778/
Twitter: https://x.com/goinggodotnet
The fastest way to install on any supported platform is with Go:
$ go install github.com/ardanlabs/malina@latest
$ malina --helpThen fetch the compatible stable-diffusion.cpp libraries:
$ malina install
$ malina systemMalina verifies the downloaded libraries automatically. Use malina install -u
to refresh them after upgrading Malina.
And pull a model bundle from the bundled catalog:
$ malina model list
$ malina model pull sd-1.5
$ malina model info -m ~/.kronk/malina-models/sd-1.5/v1-5-pruned-emaonly.safetensorsHere is the existing Issues/Features for the project and the things being worked on or things that would be nice to have.
If you are interested in helping in any way, please send an email to Bill Kennedy.
Malina calls stable-diffusion.cpp through purego and JupiterRider/ffi, without CGo. Native options copy strings and arrays and retain input tensors. Malina copies result pixels, audio, and generation metadata into Go-owned values before releasing the native result with its matching library allocator. The Go API supports image and video generation, image editing, ControlNet, upscaling, and face refinement. See the API reference for integration details.
Start with a curated bundle: Malina downloads the files needed for each workflow and keeps them together. Download sizes below are approximate and do not represent runtime memory requirements.
| Bundle | Use | Download |
|---|---|---|
sd-1.5 |
General-purpose image generation; a good starting point | 4.3 GB |
sdxl-base-1.0 |
Higher-quality image generation with Stable Diffusion XL | 6.9 GB |
controlnet-union-sdxl |
SDXL base with multi-task ControlNet Union; set ImgGenParams.ControlType |
9.5 GB |
z-image-turbo |
Fast text-to-image generation | 6.7 GB |
moss-image-sft |
Text-to-image generation with MOSS-Image | 9.4 GB |
llada-image-turbo |
Text-to-image generation and image editing | 20.2 GB |
flux2-klein-4b |
Compact FLUX image generation; license-gated | 5.3 GB |
flux2-klein-9b |
Larger FLUX image generation; license-gated | 16 GB |
controlnet-canny-sd1.5 |
Guide image generation with Canny edges | 2.3 GB |
z-image-turbo-controlnet-union |
Guide Z-Image generation with supplied control maps | 13.4 GB |
realesrgan-x4-anime |
Enlarge anime-style images 4× | 18 MB |
adetailer-face-yolov8n |
Detect and refine faces | 1.6 GB |
animatediff-sd1.5 |
Generate video with AnimateDiff | 2.4 GB |
wan2.2-s2v-14b |
Audio-conditioned video generation | 18.4 GB |
List the catalog and download a bundle:
$ malina model list
$ malina model pull sd-1.5Bundles are stored under ~/.kronk/malina-models/<bundle>/. Review the
license shown by malina model list before use. For license-gated bundles,
accept the upstream Hugging Face terms and set HF_TOKEN before downloading.
The FLUX Klein bundles carry non-commercial license terms.
You can also supply your own .safetensors or .gguf models and their
required components through the Go API. Supported families include Stable
Diffusion, SDXL, SD3, and FLUX, among others supported by the compatible
stable-diffusion.cpp library. See the upstream model guides
for requirements beyond the curated catalog.
Malina installs prebuilt libraries from stable-diffusion.cpp for these platforms:
| OS | CPU | Backends |
|---|---|---|
| macOS | arm64 | Metal |
| Windows | amd64 | CPU, CUDA, Vulkan, ROCm |
| Linux | amd64 | CPU, Vulkan, ROCm |
Use the compatible library listed in the grid above. The installer selects the default for your Malina installation; you do not need to choose an upstream archive manually.
There are examples in the examples/ directory. They load
verified libraries and models from Malina's default locations under
~/.kronk. Install the libraries and the required bundle before running:
$ malina install -u
$ malina model pull sd-1.5SYSTEM — the smallest possible malina program: load libstable-diffusion and print the library version, system info, and GGML backend device count. No model required.
$ make example-systemHELLO — load a stable-diffusion model, generate one image from a text prompt, and save it as hello.png.
$ make example-helloCONCURRENT — compare serial generation with concurrent generation on independent native contexts. Contexts cannot be shared concurrently, and each independent context loads another copy of the model weights.
$ make example-concurrentIMG2IMG — image-to-image: load a source PNG or JPEG, hand it to stable-diffusion as the starting latent, and let the prompt repaint it. The default chain consumes hello.png written by the previous example.
$ make example-hello # writes hello.png
$ make example-img2img # writes img2img.png in oil-painting styleCONTROLNET — derive Canny edges from an input image and use them to constrain the generated image's composition.
$ malina model pull controlnet-canny-sd1.5
$ make example-controlnetUPSCALE — enlarge an image 4× with the compact Real-ESRGAN anime model.
$ malina model pull realesrgan-x4-anime
$ make example-upscaleADETAILER — detect faces with YOLOv8n and refine each detected region with Stable Diffusion inpainting.
$ malina model pull adetailer-face-yolov8n
$ make example-adetailerANIMATEDIFF — generate a temporally conditioned sequence with an AnimateDiff motion module and save it as an AVI.
$ malina model pull animatediff-sd1.5
$ make example-animatediffSD-ENCODE — mux a directory of PNG / JPEG frames into a Motion-JPEG AVI. No model is loaded; this is the pure-Go encoder built on top of pkg/sd's SaveAVI helper.
$ make example-sd-encode// hello is the smallest possible malina example: load a stable-diffusion
// model, generate one image from a text prompt, and save it as PNG.
package main
import (
"context"
"fmt"
"log"
"os"
"path/filepath"
"time"
"github.com/ardanlabs/malina/pkg/download"
"github.com/ardanlabs/malina/pkg/sd"
)
func main() {
prompt := "a lovely cat"
if len(os.Args) >= 2 {
prompt = os.Args[1]
}
libPath := download.DefaultLibrariesDir()
bundleDir := filepath.Join(download.DefaultModelsDir(), "sd-1.5")
manifest, err := download.LoadManifest(bundleDir)
if err != nil {
log.Fatalf("load model bundle from %s: %v (did you run `malina model pull sd-1.5`?)", bundleDir, err)
}
modelPath := manifest.Files[string(download.RoleModel)]
if err := download.VerifyDefaultInstall(context.Background(), libPath); err != nil {
log.Fatalf("verify default libraries: %v (did you run `malina install -u`?)", err)
}
if err := sd.Load(libPath); err != nil {
log.Fatalf("sd.Load: %v", err)
}
if err := sd.Init(libPath); err != nil {
log.Fatalf("sd.Init: %v", err)
}
cparams := sd.ContextParamsInit()
cparams.ModelPath = modelPath
fmt.Println("loading model from", modelPath, "...")
ctx, err := sd.NewContext(cparams)
if err != nil {
log.Fatalf("sd.NewContext: %v", err)
}
defer sd.FreeContext(ctx)
params := sd.ImgGenParamsInit()
params.Prompt = prompt
fmt.Println("generating image for prompt:", prompt)
start := time.Now()
img, err := sd.GenerateImage(ctx, params)
if err != nil {
log.Fatalf("sd.GenerateImage: %v", err)
}
elapsed := time.Since(start)
const outPath = "hello.png"
if err := img.SavePNG(outPath); err != nil {
log.Fatalf("SavePNG: %v", err)
}
fmt.Printf("wrote %s (%dx%d, %d channels) in %s\n", outPath, img.Width, img.Height, img.Channel, elapsed.Round(time.Millisecond))
}This example produces the following output:
$ make example-hello
go run ./examples/hello "a lovely cat"
loading model from /Users/bill/.kronk/malina-models/sd-1.5/v1-5-pruned-emaonly.safetensors ...
generating image for prompt: a lovely cat
wrote hello.png (512x512, 3 channels) in 6.842sApache-2.0 — see LICENSE.