●Change8

Migrating to LocalAI v4.0.0

Version v4.0.0 introduces 2 breaking changes. This guide details how to update your code.

Released: 3/14/2026

2
Breaking Changes
4
Migration Steps
22
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

HuggingFace backendAIO imageswatchdoghealth check logsjson_verboseverbose_jsonembedding dimension calculationmodel install file permissionsDocker Compose files (Windows)YAML config reloadingchat reasoning blocksdiffusers backend (img2img pipeline)Qwen TTSGPU vendor checksMLX Distributed backendfish-speech backendace-step.cpp backendfaster-qwen3-tts backendRealtime APITalk page (WebRTC)Qwen TTS (sample_rate)vllm-omni backend

Breaking Changes

●Issue #1

HuggingFace backend support has been removed. Users relying on this backend must migrate to other supported backends.

●Issue #2

AIO images have been dropped. Users should switch to the main LocalAI images.

Migration Steps

  1. 1
    If you were using the HuggingFace backend, you must migrate to a supported alternative.
  2. 2
    If you were using AIO images, switch to the main LocalAI images.
  3. 3
    If you need to separate persistent data (agents, skills) from configuration, use the new `--data-path` CLI flag or set the `LOCALAI_DATA_PATH` environment variable.
  4. 4
    If you relied on the old `json_verbose` parameter, rename it to `verbose_json` for OpenAI spec compliance.

Release Summary

LocalAI 4.0.0 transforms the platform into a complete AI orchestration system, introducing native agentic capabilities, a completely revamped React UI, and expanded MCP support. This major release also adds experimental MLX Distributed support and several new audio backends.

Need More Details?

View the full release notes and all changes for LocalAI v4.0.0.

View Full Changelog