fix(python): import converters and specs lazily so inference does not load torch

[Anai-Guo]

Fixes #2078 (#2079 is a duplicate of the same report).

Problem

import ctranslate2 unconditionally imports torch, transformers and huggingface_hub when they are present in the environment, even for inference-only use (Translator / Generator / Whisper).

python/ctranslate2/__init__.py ends with:

from ctranslate2 import converters, models, specs

• converters/__init__.py imports converters.transformers, which does try: import huggingface_hub, torch, transformers.
• specs/model_spec.py does try: import torch to set torch_is_available.

Both are only needed for model conversion, never for inference — so every inference-only user with torch installed pays the import cost. As the reporter notes, this also forces users who mix CTranslate2 inference with onnxruntime in one process to shell out to a subprocess just to keep torch out of it.

Change

Import converters and specs on first attribute access using a module-level __getattr__ (PEP 562), plus a matching __dir__. models stays eager — it only imports from the compiled _ext, so it costs nothing.

Compatibility

All existing access patterns still work, verified against an installed 4.7.1 with the patch applied:

form	result
import ctranslate2; ctranslate2.converters.TransformersConverter	ok (triggers lazy import)
import ctranslate2; ctranslate2.specs.TransformerSpec	ok
from ctranslate2 import converters	ok
from ctranslate2 import specs	ok
import ctranslate2.converters	ok
from ctranslate2.converters import TransformersConverter	ok
from ctranslate2.specs import TransformerSpec	ok
from ctranslate2.specs import model_spec → torch_is_available	True
'converters' in dir(ctranslate2) / 'specs' in dir(...)	True
ctranslate2.does_not_exist	raises AttributeError

All 6 ct2-*-converter console_scripts entry points still resolve (ctranslate2.converters.{transformers,opennmt_py,fairseq,marian,opus_mt,openai_gpt2}:main — each imports and exposes a callable main).

Measurements

Windows, Python 3.12.10, torch 2.5.1+cu121, ctranslate2 4.7.1:

	import ctranslate2 (subprocess, min of 3)	package subtree (-X importtime)
before	3.04 s	2.73 s
after	0.15 s	0.11 s

before: torch in sys.modules = True,  transformers in sys.modules = True
after:  torch in sys.modules = False, transformers in sys.modules = False

Test

Added test_import_does_not_load_conversion_dependencies to python/tests/test_misc.py, parametrized over torch and transformers. It runs import ctranslate2 in a subprocess (the test session itself imports both, so an in-process check would be meaningless).

Against the installed package:

before fix: 2 failed, 2 passed   (both new params fail: got True, expected False)
after fix:  4 passed

black, isort (profile=black, lines_between_types=1) and flake8 (max-line-length=100) are clean on both changed files.

---

AI disclosure, per CONTRIBUTING.md: this change was written with AI assistance (Claude Code). The reported import chain was verified by reading the actual source on master, and every claim above — the compatibility matrix, entry points, timings, and before/after test results — was produced by running it locally against an installed CTranslate2, not inferred.

🤖 Generated with Claude Code

[jordimas]

Thanks for your work

Could we add a small regression test for from ctranslate2 import *?

Before this change, wildcard imports exposed converters and specs. Since wildcard import uses __all__ if defined, otherwise current module globals, it would be good to check that this behavior is still preserved with the lazy imports.