{"id":9026,"library":"groundingdino-py","title":"Grounding DINO Python Wrapper","description":"groundingdino-py is a Python wrapper for the Grounding DINO open-set object detection model, simplifying its installation and usage. It provides a user-friendly interface to load models, process images, and perform text-prompted object detection. The current version is 0.4.0, with releases occurring semi-frequently to address installation issues and add features.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/giswqs/GroundingDINO","tags":["computer vision","object detection","open-set detection","groundingdino","deep learning"],"install":[{"cmd":"pip install groundingdino-py","lang":"bash","label":"For CPU inference"},{"cmd":"pip install groundingdino-py[cuda]","lang":"bash","label":"For GPU inference (requires compatible PyTorch and CUDA)"}],"dependencies":[{"reason":"Core deep learning framework for the underlying model.","package":"torch","optional":false},{"reason":"Used for image processing utilities alongside PyTorch.","package":"torchvision","optional":false},{"reason":"Leverages Hugging Face Transformers for model architecture and tokenizer.","package":"transformers","optional":false},{"reason":"Manages model downloads from Hugging Face.","package":"huggingface-hub","optional":false},{"reason":"Potentially used for optimized model loading and inference.","package":"accelerate","optional":false},{"reason":"Optional dependency for improved GPU performance with the [cuda] extra.","package":"xformers","optional":true}],"imports":[{"note":"This wrapper uses a simplified import path compared to the original GroundingDINO project (IDEA-Research/GroundingDINO).","wrong":"from GroundingDINO import groundingdino_model","symbol":"GroundingDINO","correct":"from groundingdino import GroundingDINO"}],"quickstart":{"code":"import os\nfrom groundingdino import GroundingDINO\n\n# Instantiate the model\nmodel = GroundingDINO() # Weights are downloaded on first run (approx. 2GB)\n\n# Download a sample image (or use your own local path)\nimage_url = \"https://raw.githubusercontent.com/giswqs/groundingdino-py/main/images/dog.jpg\"\nimage_path = \"dog.jpg\"\nif not os.path.exists(image_path):\n    print(f\"Downloading {image_path}...\")\n    model.download_file(image_url, image_path) # Helper method from the wrapper\n\n# Define the text prompt\ntext_prompt = \"a dog, a leash\"\n\n# Predict objects in the image\n# Returns bounding boxes, confidence scores, and detected phrases\nboxes, logits, phrases = model.predict_image(image_path, text_prompt)\n\nprint(f\"Image: {image_path}\")\nprint(f\"Text prompt: '{text_prompt}'\")\nprint(f\"Detected boxes (xyxy format): {boxes}\")\nprint(f\"Confidence scores: {logits}\")\nprint(f\"Detected phrases: {phrases}\")\n\n# You can also customize confidence thresholds during prediction:\n# boxes, logits, phrases = model.predict_image(image_path, text_prompt, box_threshold=0.3, text_threshold=0.25)","lang":"python","description":"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."},"warnings":[{"fix":"Always 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()`).","message":"The `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.","severity":"breaking","affected_versions":"All versions of groundingdino-py (0.1.0+)"},{"fix":"Ensure 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())`.","message":"For 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.","severity":"gotcha","affected_versions":"All versions (0.1.0+)"},{"fix":"Be 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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions (0.1.0+)"},{"fix":"For practical applications and better performance, a GPU is highly recommended. Install with `groundingdino-py[cuda]` and ensure PyTorch is configured correctly for your GPU.","message":"Grounding DINO models are computationally intensive. Running inference on a CPU will be significantly slower than on a dedicated GPU.","severity":"gotcha","affected_versions":"All versions (0.1.0+)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change the import statement to `from groundingdino import GroundingDINO`.","cause":"Attempting to use import paths from the original GroundingDINO repository (e.g., IDEA-Research/GroundingDINO) instead of the `groundingdino-py` wrapper.","error":"ModuleNotFoundError: No module named 'GroundingDINO'"},{"fix":"Reduce the input image size, free up GPU memory by closing other applications, or use a GPU with more VRAM. For `groundingdino-py[cuda]`, consider installing `xformers` for potential memory optimization.","cause":"Processing images that are too large, running multiple GPU-intensive tasks, or using a GPU with insufficient VRAM for the model.","error":"RuntimeError: CUDA error: out of memory"},{"fix":"Refer to the `groundingdino-py` documentation and use the correct method, which is `model.predict_image()`.","cause":"Using a method name (e.g., `predict`) that exists in the original GroundingDINO project but not in the `groundingdino-py` wrapper, or an older/incompatible version of the wrapper.","error":"AttributeError: 'GroundingDINO' object has no attribute 'predict'"},{"fix":"Reinstall with `pip install --force-reinstall groundingdino-py[cuda]`. Ensure your CUDA toolkit and GPU drivers are up to date and compatible with the PyTorch version installed. Check `torch.version.cuda`.","cause":"`groundingdino-py[cuda]` was not installed, or the installed `torch` version is not compatible with your CUDA toolkit or GPU drivers.","error":"`torch.cuda.is_available()` returns False` despite having a GPU."}]}