Ultralytics HUB-SDK

Welcome to the Ultralytics HUB-SDK documentation! 📖 This guide will walk you through the installation process and help you get started using the HUB-SDK for your machine learning (ML) projects. The SDK provides tools to interact programmatically with Ultralytics HUB.

🚀 Quickstart: Installing HUB-SDK

Ready to dive into the HUB-SDK? Follow these steps to set it up on your machine.

Prerequisites

Before you begin, ensure your system meets the following requirements:

• Python: The HUB-SDK requires Python 3.8 or later. If you don't have Python installed, download it from the official Python website.
• Git (Optional): If you plan to install the HUB-SDK directly from the GitHub repository or contribute to the project, you'll need Git. Install Git from git-scm.com if necessary.

Installation Methods

You can install the HUB-SDK using either of the following methods:

Install from PyPI

For the latest stable release, install the HUB-SDK from PyPI using pip:

pip install hub-sdk

Install from GitHub

To get the very latest development version, you can clone the repository and install it locally:

git clone https://github.com/ultralytics/hub-sdk.git
cd hub-sdk
pip install -e .

🛠️ Usage

Let's get started using the HUB-SDK to perform Create, Read, Update, and Delete (CRUD) operations for Models, Datasets, and Projects on Ultralytics HUB.

1. Authenticate with Credentials

You need to authenticate your client. Choose one of the following methods:

Using an API Key

You can find or generate your API key in your Ultralytics HUB account settings.

# Authenticate using your API key
credentials = {"api_key": "YOUR_API_KEY"}

Using Email and Password

Alternatively, authenticate using your Ultralytics HUB email and password.

# Authenticate using your email and password
credentials = {"email": "YOUR_EMAIL", "password": "YOUR_PASSWORD"}

2. Initialize the HUBClient

Instantiate the HUBClient with your chosen credentials:

# Initialize the client with your credentials
from hub_sdk import HUBClient

client = HUBClient(credentials)

Operations

The following code snippets demonstrate how to perform CRUD operations on Projects, Models, and Datasets using the initialized client.

Project Operations

Manage your projects easily:

# Get a specific project by its ID
project = client.project("PROJECT_ID")

# Create a new project
project = client.project()
project.create_project({"meta": {"name": "My Project"}})

# List projects
projects = client.project_list(page_size=10)

# Update an existing project
project = client.project("PROJECT_ID")
project.update({"meta": {"name": "Updated Project"}})

# Delete the project
project.delete()

Model Operations

Handle your models efficiently:

# Get a specific model by its ID
model = client.model("MODEL_ID")

# Create a new model
model = client.model()
model.create_model(
    {
        "meta": {"name": "My Model"},
        "projectId": "PROJECT_ID",
        "datasetId": "DATASET_ID",
        "config": {
            "batchSize": -1,
            "cache": "ram",
            "device": "cpu",
            "epochs": 5,
            "imageSize": 640,
            "patience": 5,
        },
    }
)

# List models associated with a project or account
models = client.model_list(page_size=10)

# Update model details
model = client.model("MODEL_ID")
model.update({"meta": {"name": "Updated Model"}})

# Upload a model checkpoint
model.upload_model(epoch=5, weights="path/to/best.pt", is_best=True)

# Delete the model
model.delete()

Dataset Operations

Dataset management is straightforward:

# Get a specific dataset by its ID
dataset = client.dataset("DATASET_ID")

# Create a new dataset
dataset = client.dataset()
dataset.create_dataset({"meta": {"name": "My Dataset"}, "filename": "dataset.zip"})

# List datasets
datasets = client.dataset_list(page_size=10)

# Update dataset details
dataset = client.dataset("DATASET_ID")
dataset.update({"meta": {"name": "Updated Dataset"}})

# Upload dataset contents
dataset.upload_dataset(file="path/to/dataset.zip")

# Delete the dataset
dataset.delete()

For additional payload fields, pagination helpers, and response details, see the HUB-SDK documentation and the source classes.

⭐ Ultralytics HUB

Experience seamless AI development with Ultralytics HUB ⭐, the ultimate platform for building, training, and deploying computer vision models. Visualize your datasets, train Ultralytics YOLO models like YOLO11 🚀, and deploy them to real-world applications without writing any code. Explore our user-friendly Ultralytics App and leverage cutting-edge tools to bring your AI visions to life. Start your journey for Free today!

💡 Contribute

We welcome contributions to our open-source projects! Your support helps us improve and grow. To get involved, please see our Contributing Guide. We also appreciate feedback – let us know your thoughts via our Survey. Thank you 🙏 to all our contributors!

📄 License

Ultralytics offers two licensing options to accommodate different use cases:

• AGPL-3.0 License: This OSI-approved open-source license is ideal for students, researchers, and enthusiasts who wish to share their work and collaborate openly. See the LICENSE file for full details.
• Enterprise License: Designed for commercial use, this license allows for the integration of Ultralytics software and AI models into commercial products and services without the open-source requirements of AGPL-3.0. If your scenario involves commercial deployment, please contact us via Ultralytics Licensing.

🤝 Contact

For bug reports and feature requests related to the HUB-SDK, please use GitHub Issues. For questions, support, and discussions with the Ultralytics team and the wider community, join our Discord!