Skip to content

VoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.

fix(setup): let small models install on low disk (2 GB headroom, warn below 10 GB)

debpalash3d28fec9e859
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a0cabda73..65c562667 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ metadata and the backend fallback mirror it.
### Changed
+- Small models now install with as little as 2 GB spare disk; the setup check only warns below 10 GB instead of blocking
- iOS Home shows Electron's contributor avatars, Dub is redesigned around one source card with animated icons, and the iOS bottom dock is icon-only (#2969)
- Model licence review on iOS and Android opens with a plain summary, rights rows and licence links; the raw terms move under Exact terms (#2969)
diff --git a/backend/api/routers/setup/models.py b/backend/api/routers/setup/models.py
index 4d16c000f..0fa663b16 100644
--- a/backend/api/routers/setup/models.py
+++ b/backend/api/routers/setup/models.py
@@ -177,6 +177,10 @@ def hf_cache_dir() -> str:
# install endpoint can't drift apart (mirrors the weight-floor single-sourcing).
_GIB = 1024 ** 3
MIN_FREE_GB = 10
+# Headroom the per-install check keeps free on top of the download, and the
+# preflight's hard floor. Smaller than MIN_FREE_GB (the comfortable-library
+# warning level) so a small model still installs on a nearly full disk.
+INSTALL_HEADROOM_GB = 2
def disk_free_bytes(path: "str | None" = None) -> int:
@@ -200,7 +204,7 @@ def disk_free_bytes(path: "str | None" = None) -> int:
def disk_space_error(to_download_bytes: "int | None", *, cache_dir: "str | None" = None) -> "str | None":
- """Actionable message when *to_download_bytes* (+ MIN_FREE_GB headroom) won't
+ """Actionable message when *to_download_bytes* (+ INSTALL_HEADROOM_GB) won't
fit on the cache volume; ``None`` when it fits, the size is unknown, or the
volume can't be probed (never block on missing information).
@@ -214,7 +218,7 @@ def disk_space_error(to_download_bytes: "int | None", *, cache_dir: "str | None"
free = disk_free_bytes(cache)
if free <= 0:
return None # couldn't probe the volume → don't block on missing info
- required = int(to_download_bytes) + MIN_FREE_GB * _GIB
+ required = int(to_download_bytes) + INSTALL_HEADROOM_GB * _GIB
if free >= required:
return None
@@ -223,7 +227,7 @@ def disk_space_error(to_download_bytes: "int | None", *, cache_dir: "str | None"
return (
f"Not enough disk space to install: this download needs {_gb(int(to_download_bytes))} "
- f"plus {MIN_FREE_GB} GB free headroom ({_gb(required)} total), but only {_gb(free)} "
+ f"plus {INSTALL_HEADROOM_GB} GB free headroom ({_gb(required)} total), but only {_gb(free)} "
f"is free at {cache}. Free up space (or move the model cache to a bigger volume) and retry."
)
@@ -662,7 +666,7 @@ def list_models():
# The headroom disk_space_error keeps free on top of every download, so
# the UI warns with the same rule (and names it) instead of a raw
# "needs 4.8 GB, 10.2 GB free" that contradicts its own refusal (#2597).
- "disk_headroom_gb": MIN_FREE_GB,
+ "disk_headroom_gb": INSTALL_HEADROOM_GB,
"platform_tags": platform_tags,
}
_set_cache(cache_key, response)
diff --git a/backend/api/routers/setup/wizard.py b/backend/api/routers/setup/wizard.py
index 35c94f9bb..9264508bf 100644
--- a/backend/api/routers/setup/wizard.py
+++ b/backend/api/routers/setup/wizard.py
@@ -23,7 +23,7 @@ from core.device_caps import KERNEL_RISK_MARKER, is_windows_on_arm
# MIN_FREE_GB + disk_free_bytes are single-sourced in ``.models`` (the lowest
# module in the setup import graph) so the wizard gate, the /models header, and
# the per-install disk guard can't drift apart.
-from .models import REQUIRED_MODELS, hf_cache_dir, is_cached, MIN_FREE_GB, disk_free_bytes
+from .models import REQUIRED_MODELS, hf_cache_dir, is_cached, MIN_FREE_GB, INSTALL_HEADROOM_GB, disk_free_bytes
from core.browser_guard import reject_cross_site_get
logger = logging.getLogger("omnivoice.setup.wizard")
@@ -55,7 +55,7 @@ def setup_status():
"hf_cache_dir": cache,
"disk_free_gb": round(free_gb, 2),
"min_free_gb": MIN_FREE_GB,
- "enough_disk": free_gb >= MIN_FREE_GB,
+ "enough_disk": free_gb >= INSTALL_HEADROOM_GB,
}
@@ -443,11 +443,17 @@ def preflight():
# ── Disk free
cache = hf_cache_dir()
free = _disk_free_gb(cache)
- if free < MIN_FREE_GB:
+ if free < INSTALL_HEADROOM_GB:
disk = {
"status": "fail",
- "detail": f"{free:.1f} GB free at {cache} (need ≥ {MIN_FREE_GB} GB)",
- "fix": f"Free up disk space or set HF_HOME to a larger partition.",
+ "detail": f"{free:.1f} GB free at {cache} (need ≥ {INSTALL_HEADROOM_GB} GB)",
+ "fix": "Free up disk space or set HF_HOME to a larger partition.",
+ }
+ elif free < MIN_FREE_GB:
+ disk = {
+ "status": "warn",
+ "detail": f"{free:.1f} GB free at {cache} ({MIN_FREE_GB}+ GB recommended)",
+ "fix": "Small models fit; free up space before installing larger ones.",
}
else:
disk = {"status": "pass", "detail": f"{free:.1f} GB free at {cache}", "fix": None}
diff --git a/docs/DESKTOP_RELEASE.md b/docs/DESKTOP_RELEASE.md
index b7645aea0..5fb041c03 100644
--- a/docs/DESKTOP_RELEASE.md
+++ b/docs/DESKTOP_RELEASE.md
@@ -162,7 +162,7 @@ Each phase produces a testable artifact. Don't proceed to the next phase until t
3. Frontend `src/pages/SetupWizard.jsx`:
- Shown when `/setup/status` says models missing.
- Per-file progress bars driven by the SSE stream.
- - Disk-space check; error state if <10 GB free.
+ - Disk-space check; error state if <2 GB free, warning below 10 GB.
- Retry on network failure.
4. App-level route guard: if `setupWizardNeeded`, render `<SetupWizard>` instead of `<Launchpad>`.
@@ -224,7 +224,7 @@ For our current goal (friend on the same M2 air), **stop at Phase D**. Cross-pla
| DMG size >800 MB | Medium | Keep nvidia/triton/matplotlib out of the spec; defer optional packs to lazy download |
| First-run download fails halfway | Medium | SSE retry + resumable `hf_hub_download` (supported natively). Show disk-space check upfront |
| Gatekeeper blocks unsigned app | Certain | Document right-click → Open as the one-time step. Long-term: buy Apple Developer ID |
-| User's friend has <10 GB free | Low | Pre-check in `/setup/status`. Refuse to start download if insufficient. Point user to clear space |
+| User's friend has <2 GB free | Low | Pre-check in `/setup/status`. Refuse to start download if insufficient. Point user to clear space |
| Apple Silicon build runs on Intel Mac | Possible | Warn in installer + app header. Don't promise cross-arch without actual Intel build |
---
diff --git a/docs/downloading-models.md b/docs/downloading-models.md
index 0abe60fdd..28e8aab1a 100644
--- a/docs/downloading-models.md
+++ b/docs/downloading-models.md
@@ -157,5 +157,5 @@ takes effect at the next retry boundary.
the engine's **Weights** list in **Model Catalogue** and install it again.
- **Out of disk** — model sizes are shown in the catalog; free space or change
the cache location with `HF_HOME` / `HF_HUB_CACHE`. An install also keeps
- 10 GB free on the model disk after the download, so it needs the download
- size plus 10 GB; the warning in Model Catalogue shows both numbers.
+ 2 GB free on the model disk after the download, so it needs the download
+ size plus 2 GB; the warning in Model Catalogue shows both numbers.
diff --git a/tests/test_install_disk_space.py b/tests/test_install_disk_space.py
index f28325564..c1f88c556 100644
--- a/tests/test_install_disk_space.py
+++ b/tests/test_install_disk_space.py
@@ -34,21 +34,21 @@ def test_rejects_when_download_exceeds_free_space(models_mod, monkeypatch):
assert msg is not None
assert "50.0 GB" in msg # needs X
assert "20.0 GB" in msg # have Z
- assert f"{models_mod.MIN_FREE_GB} GB" in msg # headroom named
+ assert f"{models_mod.INSTALL_HEADROOM_GB} GB" in msg # headroom named
assert "/fake/cache" in msg # where
def test_rejects_when_download_plus_headroom_exceeds_free(models_mod, monkeypatch):
- # Fits the raw bytes but NOT the MIN_FREE_GB headroom on top → still rejected,
+ # Fits the raw bytes but NOT the INSTALL_HEADROOM_GB headroom on top → still rejected,
# so "Install all" can't fill the disk to the brim.
- monkeypatch.setattr(models_mod, "disk_free_bytes", lambda *a, **k: 12 * _GIB)
- msg = models_mod.disk_space_error(5 * _GIB) # 5 + 10 headroom = 15 > 12 free
+ monkeypatch.setattr(models_mod, "disk_free_bytes", lambda *a, **k: 6 * _GIB)
+ msg = models_mod.disk_space_error(5 * _GIB) # 5 + 2 headroom = 7 > 6 free
assert msg is not None
assert "5.0 GB" in msg
def test_allows_when_enough_space(models_mod, monkeypatch):
- # 5 GB download + 10 GB headroom = 15 GB required, 100 GB free → proceeds.
+ # 5 GB download + 2 GB headroom = 7 GB required, 100 GB free → proceeds.
monkeypatch.setattr(models_mod, "disk_free_bytes", lambda *a, **k: 100 * _GIB)
assert models_mod.disk_space_error(5 * _GIB) is None
@@ -225,4 +225,10 @@ def test_catalogue_reports_the_headroom_the_install_guard_enforces(models_mod, m
out = models_mod.list_models()
finally:
models_mod.invalidate_cache()
- assert out["disk_headroom_gb"] == models_mod.MIN_FREE_GB
+ assert out["disk_headroom_gb"] == models_mod.INSTALL_HEADROOM_GB
+
+
+def test_small_model_fits_on_a_nearly_full_disk(models_mod, monkeypatch):
+ # 3.9 GB free is enough for a 1 GB model; the old 10 GB headroom refused it.
+ monkeypatch.setattr(models_mod, "disk_free_bytes", lambda *a, **k: int(3.9 * _GIB))
+ assert models_mod.disk_space_error(1 * _GIB) is None