Skip to content

Register now for

# Reference for `ultralytics/hub/__init__.py`

Note

This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/hub/__init__.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!

## `` ultralytics.hub.login

    login(api_key: str = None, save: bool = True) -> bool

Log in to the Ultralytics HUB API using the provided API key.

The session is not stored; a new session is created when needed using the saved SETTINGS or the HUB_API_KEY environment variable if successfully authenticated.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`api_key` | `str` | API key to use for authentication. If not provided, it will be retrieved from SETTINGS or HUB_API_KEY environment variable. | `None`
`save` | `bool` | Whether to save the API key to SETTINGS if authentication is successful. | `True`

Returns:

Type | Description
--- | ---
`bool` | True if authentication is successful, False otherwise.

Source code in `ultralytics/hub/__init__.py`

    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    def login(api_key: str = None, save: bool = True) -> bool:
        """
        Log in to the Ultralytics HUB API using the provided API key.

        The session is not stored; a new session is created when needed using the saved SETTINGS or the HUB_API_KEY
        environment variable if successfully authenticated.

        Args:
            api_key (str, optional): API key to use for authentication. If not provided, it will be retrieved from
                SETTINGS or HUB_API_KEY environment variable.
            save (bool, optional): Whether to save the API key to SETTINGS if authentication is successful.

        Returns:
            (bool): True if authentication is successful, False otherwise.
        """
        checks.check_requirements("hub-sdk>=0.0.12")
        from hub_sdk import HUBClient

        api_key_url = f"{HUB_WEB_ROOT}/settings?tab=api+keys"  # set the redirect URL
        saved_key = SETTINGS.get("api_key")
        active_key = api_key or saved_key
        credentials = {"api_key": active_key} if active_key and active_key != "" else None  # set credentials

        client = HUBClient(credentials)  # initialize HUBClient

        if client.authenticated:
            # Successfully authenticated with HUB

            if save and client.api_key != saved_key:
                SETTINGS.update({"api_key": client.api_key})  # update settings with valid API key

            # Set message based on whether key was provided or retrieved from settings
            log_message = (
                "New authentication successful ✅" if client.api_key == api_key or not credentials else "Authenticated ✅"
            )
            LOGGER.info(f"{PREFIX}{log_message}")

            return True
        else:
            # Failed to authenticate with HUB
            LOGGER.info(f"{PREFIX}Get API key from {api_key_url} and then run 'yolo login API_KEY'")
            return False

## `` ultralytics.hub.logout

    logout()

Log out of Ultralytics HUB by removing the API key from the settings file.

Source code in `ultralytics/hub/__init__.py`

    67
    68
    69
    70
    def logout():
        """Log out of Ultralytics HUB by removing the API key from the settings file."""
        SETTINGS["api_key"] = ""
        LOGGER.info(f"{PREFIX}logged out ✅. To log in again, use 'yolo login'.")

## `` ultralytics.hub.reset_model

    reset_model(model_id: str = '')

Reset a trained model to an untrained state.

Source code in `ultralytics/hub/__init__.py`

    73
    74
    75
    76
    77
    78
    79
    80
    81
    def reset_model(model_id: str = ""):
        """Reset a trained model to an untrained state."""
        import requests  # scoped as slow import

        r = requests.post(f"{HUB_API_ROOT}/model-reset", json={"modelId": model_id}, headers={"x-api-key": Auth().api_key})
        if r.status_code == 200:
            LOGGER.info(f"{PREFIX}Model reset successfully")
            return
        LOGGER.warning(f"{PREFIX}Model reset failure {r.status_code} {r.reason}")

## `` ultralytics.hub.export_fmts_hub

    export_fmts_hub()

Return a list of HUB-supported export formats.

Source code in `ultralytics/hub/__init__.py`

    84
    85
    86
    87
    88
    def export_fmts_hub():
        """Return a list of HUB-supported export formats."""
        from ultralytics.engine.exporter import export_formats

        return list(export_formats()["Argument"][1:]) + ["ultralytics_tflite", "ultralytics_coreml"]

## `` ultralytics.hub.export_model

    export_model(model_id: str = '', format: str = 'torchscript')

Export a model to a specified format for deployment via the Ultralytics HUB API.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`model_id` | `str` | The ID of the model to export. An empty string will use the default model. | `''`
`format` | `str` | The format to export the model to. Must be one of the supported formats returned by export_fmts_hub(). | `'torchscript'`

Raises:

Type | Description
--- | ---
`AssertionError` | If the specified format is not supported or if the export request fails.

Examples:

    >>> from ultralytics import hub
    >>> hub.export_model(model_id="your_model_id", format="torchscript")

Source code in `ultralytics/hub/__init__.py`

     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    def export_model(model_id: str = "", format: str = "torchscript"):
        """
        Export a model to a specified format for deployment via the Ultralytics HUB API.

        Args:
            model_id (str): The ID of the model to export. An empty string will use the default model.
            format (str): The format to export the model to. Must be one of the supported formats returned by
                export_fmts_hub().

        Raises:
            AssertionError: If the specified format is not supported or if the export request fails.

        Examples:
            >>> from ultralytics import hub
            >>> hub.export_model(model_id="your_model_id", format="torchscript")
        """
        import requests  # scoped as slow import

        assert format in export_fmts_hub(), f"Unsupported export format '{format}', valid formats are {export_fmts_hub()}"
        r = requests.post(
            f"{HUB_API_ROOT}/v1/models/{model_id}/export", json={"format": format}, headers={"x-api-key": Auth().api_key}
        )
        assert r.status_code == 200, f"{PREFIX}{format} export failure {r.status_code} {r.reason}"
        LOGGER.info(f"{PREFIX}{format} export started ✅")

## `` ultralytics.hub.get_export

    get_export(model_id: str = '', format: str = 'torchscript')

Retrieve an exported model in the specified format from Ultralytics HUB using the model ID.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`model_id` | `str` | The ID of the model to retrieve from Ultralytics HUB. | `''`
`format` | `str` | The export format to retrieve. Must be one of the supported formats returned by export_fmts_hub(). | `'torchscript'`

Returns:

Type | Description
--- | ---
`dict` | JSON response containing the exported model information.

Raises:

Type | Description
--- | ---
`AssertionError` | If the specified format is not supported or if the API request fails.

Examples:

    >>> from ultralytics import hub
    >>> result = hub.get_export(model_id="your_model_id", format="torchscript")

Source code in `ultralytics/hub/__init__.py`

    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    def get_export(model_id: str = "", format: str = "torchscript"):
        """
        Retrieve an exported model in the specified format from Ultralytics HUB using the model ID.

        Args:
            model_id (str): The ID of the model to retrieve from Ultralytics HUB.
            format (str): The export format to retrieve. Must be one of the supported formats returned by
                export_fmts_hub().

        Returns:
            (dict): JSON response containing the exported model information.

        Raises:
            AssertionError: If the specified format is not supported or if the API request fails.

        Examples:
            >>> from ultralytics import hub
            >>> result = hub.get_export(model_id="your_model_id", format="torchscript")
        """
        import requests  # scoped as slow import

        assert format in export_fmts_hub(), f"Unsupported export format '{format}', valid formats are {export_fmts_hub()}"
        r = requests.post(
            f"{HUB_API_ROOT}/get-export",
            json={"apiKey": Auth().api_key, "modelId": model_id, "format": format},
            headers={"x-api-key": Auth().api_key},
        )
        assert r.status_code == 200, f"{PREFIX}{format} get_export failure {r.status_code} {r.reason}"
        return r.json()

## `` ultralytics.hub.check_dataset

    check_dataset(path: str, task: str) -> None

Check HUB dataset Zip file for errors before upload.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`path` | `str` | Path to data.zip (with data.yaml inside data.zip). | required
`task` | `str` | Dataset task. Options are 'detect', 'segment', 'pose', 'classify', 'obb'. | required

Examples:

    >>> from ultralytics.hub import check_dataset
    >>> check_dataset("path/to/coco8.zip", task="detect")  # detect dataset
    >>> check_dataset("path/to/coco8-seg.zip", task="segment")  # segment dataset
    >>> check_dataset("path/to/coco8-pose.zip", task="pose")  # pose dataset
    >>> check_dataset("path/to/dota8.zip", task="obb")  # OBB dataset
    >>> check_dataset("path/to/imagenet10.zip", task="classify")  # classification dataset

Notes

Download *.zip files from https://github.com/ultralytics/hub/tree/main/example_datasets i.e. https://github.com/ultralytics/hub/raw/main/example_datasets/coco8.zip for coco8.zip.

Source code in `ultralytics/hub/__init__.py`

    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    def check_dataset(path: str, task: str) -> None:
        """
        Check HUB dataset Zip file for errors before upload.

        Args:
            path (str): Path to data.zip (with data.yaml inside data.zip).
            task (str): Dataset task. Options are 'detect', 'segment', 'pose', 'classify', 'obb'.

        Examples:
            >>> from ultralytics.hub import check_dataset
            >>> check_dataset("path/to/coco8.zip", task="detect")  # detect dataset
            >>> check_dataset("path/to/coco8-seg.zip", task="segment")  # segment dataset
            >>> check_dataset("path/to/coco8-pose.zip", task="pose")  # pose dataset
            >>> check_dataset("path/to/dota8.zip", task="obb")  # OBB dataset
            >>> check_dataset("path/to/imagenet10.zip", task="classify")  # classification dataset

        Notes:
            Download *.zip files from https://github.com/ultralytics/hub/tree/main/example_datasets
            i.e. https://github.com/ultralytics/hub/raw/main/example_datasets/coco8.zip for coco8.zip.
        """
        HUBDatasetStats(path=path, task=task).get_json()
        LOGGER.info(f"Checks completed correctly ✅. Upload this dataset to {HUB_WEB_ROOT}/datasets/.")

📅 Created 1 year ago ✏️ Updated 1 year ago