Install & Compatibility
Where this runs
tested against v0.4.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
✓ 94.93s
py 3.11
✕ build_error
✓ 88.03s
py 3.12
✕ build_error
✓ 80.93s
py 3.13
✕ build_error
✓ 73.65s
py 3.9
✕ build_error
✕ timeout
5299MB installed
● package 5299MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GroundingDINO
✓ import groundingdino
✗ from groundingdino import GroundingDINO
Initializes the GroundingDINO model, downloads a sample image (if not present), and performs open-set object detection using a text prompt. The model weights are downloaded automatically on the first instantiation. The `predict_image` method returns bounding box coordinates, confidence scores, and the corresponding detected phrases.
import os
from groundingdino import GroundingDINO
# Instantiate the model
model = GroundingDINO() # Weights are downloaded on first run (approx. 2GB)
# Download a sample image (or use your own local path)
image_url = "https://raw.githubusercontent.com/giswqs/groundingdino-py/main/images/dog.jpg"
image_path = "dog.jpg"
if not os.path.exists(image_path):
print(f"Downloading {image_path}...")
model.download_file(image_url, image_path) # Helper method from the wrapper
# Define the text prompt
text_prompt = "a dog, a leash"
# Predict objects in the image
# Returns bounding boxes, confidence scores, and detected phrases
boxes, logits, phrases = model.predict_image(image_path, text_prompt)
print(f"Image: {image_path}")
print(f"Text prompt: '{text_prompt}'")
print(f"Detected boxes (xyxy format): {boxes}")
print(f"Confidence scores: {logits}")
print(f"Detected phrases: {phrases}")
# You can also customize confidence thresholds during prediction:
# boxes, logits, phrases = model.predict_image(image_path, text_prompt, box_threshold=0.3, text_threshold=0.25)
Debug
Known issues
breakingThe `groundingdino-py` wrapper uses different import paths and method names compared to the original GroundingDINO repository (IDEA-Research/GroundingDINO). Direct copy-pasting code from the original project will likely fail.fixAlways refer to the `groundingdino-py` documentation and examples for correct imports (e.g., `from groundingdino import GroundingDINO`) and method calls (e.g., `model.predict_image()`).
affects: All versions of groundingdino-py (0.1.0+)
gotchaFor GPU acceleration, you must install the library with the `[cuda]` extra (e.g., `pip install groundingdino-py[cuda]`). This requires a compatible PyTorch installation and CUDA toolkit on your system.fixEnsure your system has CUDA drivers and toolkit installed. Then, install with `pip install groundingdino-py[cuda]`. Verify GPU availability with `import torch; print(torch.cuda.is_available())`.
affects: All versions (0.1.0+)
gotchaThe Grounding DINO model weights (approx. 2GB) are downloaded automatically on the first instantiation of the `GroundingDINO()` class. This requires an active internet connection and can take some time.fixBe prepared for a delay and network activity on the first run. Ensure sufficient disk space and a stable internet connection. Subsequent runs will load weights from cache.
affects: All versions (0.1.0+)
gotchaGrounding DINO models are computationally intensive. Running inference on a CPU will be significantly slower than on a dedicated GPU.fixFor practical applications and better performance, a GPU is highly recommended. Install with `groundingdino-py[cuda]` and ensure PyTorch is configured correctly for your GPU.
affects: All versions (0.1.0+)
Upgrade
Version history
0.4.0latest on PyPI · released May 23, 2023
Audit
Dependencies
torchrequiredCore deep learning framework for the underlying model.
torchvisionrequiredUsed for image processing utilities alongside PyTorch.
transformersrequiredLeverages Hugging Face Transformers for model architecture and tokenizer.
huggingface-hubrequiredManages model downloads from Hugging Face.
acceleraterequiredPotentially used for optimized model loading and inference.
xformersoptionalOptional dependency for improved GPU performance with the [cuda] extra.