Skip to content

feat: optional dependency groups for backends#186

Open
sorlen008 wants to merge 1 commit intoabsadiki:mainfrom
sorlen008:feat/optional-dependency-groups
Open

feat: optional dependency groups for backends#186
sorlen008 wants to merge 1 commit intoabsadiki:mainfrom
sorlen008:feat/optional-dependency-groups

Conversation

@sorlen008
Copy link
Copy Markdown
Contributor

Summary

  • Move backend-specific dependencies into [project.optional-dependencies] in pyproject.toml, so users install only what they need instead of every backend at once
  • Keep base deps minimal: pysubs2, ffmpeg-python, ffsubsync, dl-translate, tqdm, numpy
  • Improve error handling in configs.py: broaden except ImportError to except Exception (catches RuntimeError from version mismatches too), replace noisy print(e) with logging.debug, downgrade fatal "no models found" error to a helpful warning with install instructions

Problem

This is the #1 user pain point -- 12+ open issues about installation failures because ALL backends are installed even if you only need one. Dependency conflicts between torch, whisperx, transformers, stable-ts, etc. make a clean install nearly impossible on many systems.

Related issues: #132, #171, #169, #164, #116, #115, #101

Solution

PR #176 laid the groundwork by making backends optional at import time (try/except in configs.py). This PR completes that work by making the pip dependencies optional too via extras.

Install examples

# Base only (no backends)
pip install git+https://github.com/absadiki/subsai.git

# Single backend
pip install "git+https://github.com/absadiki/subsai.git#egg=subsai[faster-whisper]"

# Multiple backends
pip install "git+https://github.com/absadiki/subsai.git#egg=subsai[faster-whisper,api]"

# Everything (old behavior)
pip install "git+https://github.com/absadiki/subsai.git#egg=subsai[all]"

Available extras

Extra Packages
whisper openai-whisper, torch, torchaudio
faster-whisper faster-whisper, openai-whisper, torch, torchaudio
stable-ts stable-ts, faster-whisper, openai-whisper, torch, torchaudio
whisperx whisperx, openai-whisper, torch, torchaudio
timestamped whisper-timestamped, openai-whisper, torch, torchaudio
whisper-cpp pywhispercpp
transformers transformers, torch
api openai, pydub, joblib
webui streamlit, pandas, streamlit-player, streamlit-aggrid
all all of the above

Test plan

  • pip install -e . (base only) -- verify from subsai import SubsAI works with no backends, shows warning
  • pip install -e ".[faster-whisper]" -- verify faster-whisper model loads
  • pip install -e ".[all]" -- verify all models load (same as old behavior)
  • Verify no noisy import errors printed to stdout when backends are missing

Backward compatibility

  • pip install subsai[all] reproduces the old behavior exactly
  • requirements.txt is kept for reference but pyproject.toml is now the source of truth for dependencies
  • The try/except pattern in configs.py (from PR allow working without all backends #176) ensures missing backends are gracefully excluded

🤖 Generated with Claude Code

Move backend-specific dependencies from requirements.txt into
[project.optional-dependencies] in pyproject.toml. Users can now install
only what they need (e.g. pip install subsai[faster-whisper]) instead of
pulling every backend and hitting dependency conflicts.

Available extras: whisper, faster-whisper, stable-ts, whisperx,
timestamped, whisper-cpp, transformers, api, webui, all

Also improves configs.py: broadens except clauses from ImportError to
Exception (catches RuntimeError from version mismatches), replaces noisy
print(e) with logging.debug, and downgrades the "no models found" fatal
error to a warning with install instructions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@absadiki
Copy link
Copy Markdown
Owner

Thanks @sorlen008 for the PR!
Separating backend-specific dependencies is definitely the right direction and aligns well with reducing installation friction.

That said, the current approach will make the Docker image useless, since it relies on requirements.txt to install all backends by default. With this change, the image would no longer include the full feature set unless extras are explicitly handled during build.

We probably need a way to support both:

  • optional installs for end users (via extras), and
  • a “full install” path for environments like Docker (e.g., a combined extra or a dedicated requirements file)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants