{"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":"python","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":[{"wrong":"from groundingdino import GroundingDINO","symbol":"GroundingDINO","correct":"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,"search_vec":"'0.4.0':50 'add':62 'address':58 'comput':64 'current':47 'deep':73 'detect':20,45,67,71 'dino':2,15 'featur':63 'frequent':56 'friend':32 'ground':1,14 'groundingdino':6,72 'groundingdino-pi':5 'imag':38 'instal':24,59 'interfac':33 'issu':60 'learn':74 'load':35 'model':21,36 'object':19,44,66 'occur':53 'open':17,69 'open-set':16,68 'perform':40 'process':37 'prompt':43 'provid':28 'py':7 'python':3,10 'releas':52 'semi':55 'semi-frequ':54 'set':18,70 'simplifi':22 'text':42 'text-prompt':41 'usag':26 'user':31 'user-friend':30 'version':48 'vision':65 'wrapper':4,11","created_at":"2026-04-16T18:48:04.863844+00:00","updated_at":"2026-04-16T18:48:04.863844+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/giswqs/GroundingDINO","docs":null,"changelog":null,"pypi":"https://pypi.org/project/groundingdino-py/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","llm-agents"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}