Install & Compatibility
Where this runs
tested against v0.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 90.05s
py 3.11
✕ build_error
✓ 82.35s
py 3.12
✕ build_error
✓ 78.05s
py 3.13
✕ build_error
✓ 68.48s
py 3.9
✕ build_error
✕ timeout
5094MB installed
● package 5094MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Config
✓ from clip_interrogator import Config
Interrogator
✓ from clip_interrogator import Interrogator
LabelTable
✓ from clip_interrogator import LabelTable
Added in v0.6.0 for custom term ranking
list_caption_models
✓ from clip_interrogator import list_caption_models
Added in v0.6.0
list_clip_models
✓ from clip_interrogator import list_clip_models
Added in v0.6.0
This quickstart initializes the CLIP Interrogator, downloads necessary models (on first run), and then generates a text prompt from a dummy image. It includes best practices for VRAM management.
import os
from PIL import Image
from clip_interrogator import Config, Interrogator
# Create a dummy image for the example to be runnable
dummy_image_path = "dummy_image_for_ci.jpg"
try:
Image.new('RGB', (224, 224), color = 'red').save(dummy_image_path)
except ImportError:
# Fallback if Pillow is not available for some reason (unlikely for this lib)
with open(dummy_image_path, 'w') as f:
f.write("dummy content")
# Configure CLIP Interrogator
ci_config = Config()
# Set model names (these will be downloaded on first run and cached)
ci_config.clip_model_name = "ViT-L-14/openai"
ci_config.caption_model_name = "blip-large" # Other options: blip-base, blip2-2.7b, blip2-flan-t5-xl, git-large-coco
# Apply low VRAM settings if available (recommended for GPUs with <12GB VRAM)
# This method was introduced in v0.5.4
if hasattr(ci_config, 'apply_low_vram_defaults'):
ci_config.apply_low_vram_defaults()
# Initialize the Interrogator. This will download models if not already cached.
print("Initializing CLIP Interrogator (models may download on first run)...")
try:
ci = Interrogator(ci_config)
print("CLIP Interrogator initialized.")
# Load an image
image = Image.open(dummy_image_path).convert("RGB")
# Perform interrogation
prompt = ci.interrogate(image)
print(f"Generated prompt: {prompt}")
except Exception as e:
print(f"Error during interrogation: {e}. Please ensure sufficient VRAM and disk space for models.")
finally:
# Clean up the dummy image
if os.path.exists(dummy_image_path):
os.remove(dummy_image_path)
Debug
Known issues
breakingSupport for `.pkl` cache files was dropped in favor of `safetensors` format. Users upgrading from versions prior to 0.5.4 may need to clear their old cache or re-download models.fixDelete old `.pkl` cache files (typically in `~/.cache/clip_interrogator`) or allow the library to redownload models in the `safetensors` format.
affects: <0.5.4 to 0.5.4+
gotchaCLIP Interrogator, especially with larger caption models like `blip-large` or `blip2-flan-t5-xl`, requires significant VRAM (10GB+). If you experience out-of-memory errors, switch to smaller models or use `apply_low_vram_defaults()`.fixUse `Config.apply_low_vram_defaults()` (available since v0.5.4) or select a less VRAM-intensive `caption_model_name` like `blip-base` or `git-large-coco`.
affects: All versions
gotchaModels are downloaded to the user's cache directory (e.g., `~/.cache/clip_interrogator` or Hugging Face cache) on first initialization. This can take time and consume several GBs of disk space.fixEnsure you have sufficient disk space and a stable internet connection for the initial setup. Subsequent runs will use cached models.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'clip_interrogator'
This error occurs when the `clip-interrogator` package is not installed or not accessible in the current Python environment.
fixInstall the library using pip: `pip install clip-interrogator==0.6.0`.
RuntimeError: CUDA out of memory
The GPU has insufficient memory to process the image and models, which require a significant amount of VRAM (typically 12GB or more).
fixReduce the image size, switch to a lower memory mode if available (e.g., `--lowvram` option in some interfaces), or run on a CPU by setting the device configuration to 'cpu'.
AttributeError: module 'clip' has no attribute 'load'
This typically happens when there's a conflict with the `clip` library installation, or an incorrect `clip` package is installed instead of the one expected by `clip-interrogator` (which often relies on `openai/CLIP`).
fixEnsure the correct CLIP library is installed by following the `clip-interrogator`'s specific installation instructions for its dependencies, often involving installing `openai/CLIP` or checking for conflicting `clip` installations.
pls check transformers.__version__>=4.36.0:: AutoProcessor, BlipForConditionalGeneration
This indicates that the installed `transformers` library version is older than what `clip-interrogator` requires, leading to issues with importing necessary components like `AutoProcessor` or `BlipForConditionalGeneration`.
fixUpdate the `transformers` library to the specified version or higher: `pip install transformers>=4.36.0`.
Upgrade
Version history
0.6.0latest on PyPI · released Mar 20, 2023
Audit
Dependencies
No dependency data recorded yet.