Skip to content

Reference for ultralytics/utils/__init__.py

Note

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


ultralytics.utils.DataExportMixin

Mixin class for exporting validation metrics or prediction results in various formats.

This class provides utilities to export performance metrics (e.g., mAP, precision, recall) or prediction results from classification, object detection, segmentation, or pose estimation tasks into various formats: Polars DataFrame, CSV and JSON.

Methods:

Name Description
to_df

Convert summary to a Polars DataFrame.

to_csv

Export results as a CSV string.

to_json

Export results as a JSON string.

tojson

Deprecated alias for to_json().

Examples:

>>> model = YOLO("yolo11n.pt")
>>> results = model("image.jpg")
>>> df = results.to_df()
>>> print(df)
>>> csv_data = results.to_csv()

to_csv

to_csv(normalize=False, decimals=5)

Export results or metrics to CSV string format.

Parameters:

Name Type Description Default
normalize bool

Normalize numeric values.

False
decimals int

Decimal precision.

5

Returns:

Type Description
str

CSV content as string.

Source code in ultralytics/utils/__init__.py
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
def to_csv(self, normalize=False, decimals=5):
    """
    Export results or metrics to CSV string format.

    Args:
       normalize (bool, optional): Normalize numeric values.
       decimals (int, optional): Decimal precision.

    Returns:
       (str): CSV content as string.
    """
    import polars as pl

    df = self.to_df(normalize=normalize, decimals=decimals)

    try:
        return df.write_csv()
    except Exception:
        # Minimal string conversion for any remaining complex types
        def _to_str_simple(v):
            if v is None:
                return ""
            elif isinstance(v, (dict, list, tuple, set)):
                return repr(v)
            else:
                return str(v)

        df_str = df.select(
            [pl.col(c).map_elements(_to_str_simple, return_dtype=pl.String).alias(c) for c in df.columns]
        )
        return df_str.write_csv()

to_df

to_df(normalize=False, decimals=5)

Create a polars DataFrame from the prediction results summary or validation metrics.

Parameters:

Name Type Description Default
normalize bool

Normalize numerical values for easier comparison.

False
decimals int

Decimal places to round floats.

5

Returns:

Type Description
DataFrame

DataFrame containing the summary data.

Source code in ultralytics/utils/__init__.py
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def to_df(self, normalize=False, decimals=5):
    """
    Create a polars DataFrame from the prediction results summary or validation metrics.

    Args:
        normalize (bool, optional): Normalize numerical values for easier comparison.
        decimals (int, optional): Decimal places to round floats.

    Returns:
        (DataFrame): DataFrame containing the summary data.
    """
    import polars as pl  # scope for faster 'import ultralytics'

    return pl.DataFrame(self.summary(normalize=normalize, decimals=decimals))

to_json

to_json(normalize=False, decimals=5)

Export results to JSON format.

Parameters:

Name Type Description Default
normalize bool

Normalize numeric values.

False
decimals int

Decimal precision.

5

Returns:

Type Description
str

JSON-formatted string of the results.

Source code in ultralytics/utils/__init__.py
204
205
206
207
208
209
210
211
212
213
214
215
def to_json(self, normalize=False, decimals=5):
    """
    Export results to JSON format.

    Args:
        normalize (bool, optional): Normalize numeric values.
        decimals (int, optional): Decimal precision.

    Returns:
        (str): JSON-formatted string of the results.
    """
    return self.to_df(normalize=normalize, decimals=decimals).write_json()





ultralytics.utils.SimpleClass

A simple base class for creating objects with string representations of their attributes.

This class provides a foundation for creating objects that can be easily printed or represented as strings, showing all their non-callable attributes. It's useful for debugging and introspection of object states.

Methods:

Name Description
__str__

Return a human-readable string representation of the object.

__repr__

Return a machine-readable string representation of the object.

__getattr__

Provide a custom attribute access error message with helpful information.

Examples:

>>> class MyClass(SimpleClass):
...     def __init__(self):
...         self.x = 10
...         self.y = "hello"
>>> obj = MyClass()
>>> print(obj)
__main__.MyClass object with attributes:

x: 10 y: 'hello'

Notes
  • This class is designed to be subclassed. It provides a convenient way to inspect object attributes.
  • The string representation includes the module and class name of the object.
  • Callable attributes and attributes starting with an underscore are excluded from the string representation.

__getattr__

__getattr__(attr)

Provide a custom attribute access error message with helpful information.

Source code in ultralytics/utils/__init__.py
266
267
268
269
def __getattr__(self, attr):
    """Provide a custom attribute access error message with helpful information."""
    name = self.__class__.__name__
    raise AttributeError(f"'{name}' object has no attribute '{attr}'. See valid attributes below.\n{self.__doc__}")

__repr__

__repr__()

Return a machine-readable string representation of the object.

Source code in ultralytics/utils/__init__.py
262
263
264
def __repr__(self):
    """Return a machine-readable string representation of the object."""
    return self.__str__()

__str__

__str__()

Return a human-readable string representation of the object.

Source code in ultralytics/utils/__init__.py
248
249
250
251
252
253
254
255
256
257
258
259
260
def __str__(self):
    """Return a human-readable string representation of the object."""
    attr = []
    for a in dir(self):
        v = getattr(self, a)
        if not callable(v) and not a.startswith("_"):
            if isinstance(v, SimpleClass):
                # Display only the module and class name for subclasses
                s = f"{a}: {v.__module__}.{v.__class__.__name__} object"
            else:
                s = f"{a}: {repr(v)}"
            attr.append(s)
    return f"{self.__module__}.{self.__class__.__name__} object with attributes:\n\n" + "\n".join(attr)





ultralytics.utils.IterableSimpleNamespace

Bases: SimpleNamespace

An iterable SimpleNamespace class that provides enhanced functionality for attribute access and iteration.

This class extends the SimpleNamespace class with additional methods for iteration, string representation, and attribute access. It is designed to be used as a convenient container for storing and accessing configuration parameters.

Methods:

Name Description
__iter__

Return an iterator of key-value pairs from the namespace's attributes.

__str__

Return a human-readable string representation of the object.

__getattr__

Provide a custom attribute access error message with helpful information.

get

Retrieve the value of a specified key, or a default value if the key doesn't exist.

Examples:

>>> cfg = IterableSimpleNamespace(a=1, b=2, c=3)
>>> for k, v in cfg:
...     print(f"{k}: {v}")
a: 1
b: 2
c: 3
>>> print(cfg)
a=1
b=2
c=3
>>> cfg.get("b")
2
>>> cfg.get("d", "default")
'default'
Notes

This class is particularly useful for storing configuration parameters in a more accessible and iterable format compared to a standard dictionary.

__getattr__

__getattr__(attr)

Provide a custom attribute access error message with helpful information.

Source code in ultralytics/utils/__init__.py
315
316
317
318
319
320
321
322
323
324
325
def __getattr__(self, attr):
    """Provide a custom attribute access error message with helpful information."""
    name = self.__class__.__name__
    raise AttributeError(
        f"""
        '{name}' object has no attribute '{attr}'. This may be caused by a modified or out of date ultralytics
        'default.yaml' file.\nPlease update your code with 'pip install -U ultralytics' and if necessary replace
        {DEFAULT_CFG_PATH} with the latest version from
        https://github.com/ultralytics/ultralytics/blob/main/ultralytics/cfg/default.yaml
        """
    )

__iter__

__iter__()

Return an iterator of key-value pairs from the namespace's attributes.

Source code in ultralytics/utils/__init__.py
307
308
309
def __iter__(self):
    """Return an iterator of key-value pairs from the namespace's attributes."""
    return iter(vars(self).items())

__str__

__str__()

Return a human-readable string representation of the object.

Source code in ultralytics/utils/__init__.py
311
312
313
def __str__(self):
    """Return a human-readable string representation of the object."""
    return "\n".join(f"{k}={v}" for k, v in vars(self).items())

get

get(key, default=None)

Return the value of the specified key if it exists; otherwise, return the default value.

Source code in ultralytics/utils/__init__.py
327
328
329
def get(self, key, default=None):
    """Return the value of the specified key if it exists; otherwise, return the default value."""
    return getattr(self, key, default)





ultralytics.utils.ThreadingLocked

ThreadingLocked()

A decorator class for ensuring thread-safe execution of a function or method.

This class can be used as a decorator to make sure that if the decorated function is called from multiple threads, only one thread at a time will be able to execute the function.

Attributes:

Name Type Description
lock Lock

A lock object used to manage access to the decorated function.

Examples:

>>> from ultralytics.utils import ThreadingLocked
>>> @ThreadingLocked()
>>> def my_function():
...    # Your code here
Source code in ultralytics/utils/__init__.py
484
485
486
def __init__(self):
    """Initialize the decorator class with a threading lock."""
    self.lock = threading.Lock()

__call__

__call__(f)

Run thread-safe execution of function or method.

Source code in ultralytics/utils/__init__.py
488
489
490
491
492
493
494
495
496
497
498
def __call__(self, f):
    """Run thread-safe execution of function or method."""
    from functools import wraps

    @wraps(f)
    def decorated(*args, **kwargs):
        """Apply thread-safety to the decorated function or method."""
        with self.lock:
            return f(*args, **kwargs)

    return decorated





ultralytics.utils.YAML

YAML()

YAML utility class for efficient file operations with automatic C-implementation detection.

This class provides optimized YAML loading and saving operations using PyYAML's fastest available implementation (C-based when possible). It implements a singleton pattern with lazy initialization, allowing direct class method usage without explicit instantiation. The class handles file path creation, validation, and character encoding issues automatically.

The implementation prioritizes performance through
  • Automatic C-based loader/dumper selection when available
  • Singleton pattern to reuse the same instance
  • Lazy initialization to defer import costs until needed
  • Fallback mechanisms for handling problematic YAML content

Attributes:

Name Type Description
_instance

Internal singleton instance storage.

yaml

Reference to the PyYAML module.

SafeLoader

Best available YAML loader (CSafeLoader if available).

SafeDumper

Best available YAML dumper (CSafeDumper if available).

Examples:

>>> data = YAML.load("config.yaml")
>>> data["new_value"] = 123
>>> YAML.save("updated_config.yaml", data)
>>> YAML.print(data)
Source code in ultralytics/utils/__init__.py
538
539
540
541
542
543
544
545
546
547
548
549
def __init__(self):
    """Initialize with optimal YAML implementation (C-based when available)."""
    import yaml

    self.yaml = yaml
    # Use C-based implementation if available for better performance
    try:
        self.SafeLoader = yaml.CSafeLoader
        self.SafeDumper = yaml.CSafeDumper
    except (AttributeError, ImportError):
        self.SafeLoader = yaml.SafeLoader
        self.SafeDumper = yaml.SafeDumper

load classmethod

load(file='data.yaml', append_filename=False)

Load YAML file to Python object with robust error handling.

Parameters:

Name Type Description Default
file str | Path

Path to YAML file.

'data.yaml'
append_filename bool

Whether to add filename to returned dict.

False

Returns:

Type Description
dict

Loaded YAML content.

Source code in ultralytics/utils/__init__.py
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
@classmethod
def load(cls, file="data.yaml", append_filename=False):
    """
    Load YAML file to Python object with robust error handling.

    Args:
        file (str | Path): Path to YAML file.
        append_filename (bool): Whether to add filename to returned dict.

    Returns:
        (dict): Loaded YAML content.
    """
    instance = cls._get_instance()
    assert str(file).endswith((".yaml", ".yml")), f"Not a YAML file: {file}"

    # Read file content
    with open(file, errors="ignore", encoding="utf-8") as f:
        s = f.read()

    # Try loading YAML with fallback for problematic characters
    try:
        data = instance.yaml.load(s, Loader=instance.SafeLoader) or {}
    except Exception:
        # Remove problematic characters and retry
        s = re.sub(r"[^\x09\x0A\x0D\x20-\x7E\x85\xA0-\uD7FF\uE000-\uFFFD\U00010000-\U0010ffff]+", "", s)
        data = instance.yaml.load(s, Loader=instance.SafeLoader) or {}

    # Check for accidental user-error None strings (should be 'null' in YAML)
    if "None" in data.values():
        data = {k: None if v == "None" else v for k, v in data.items()}

    if append_filename:
        data["yaml_file"] = str(file)
    return data

print classmethod

print(yaml_file)

Pretty print YAML file or object to console.

Parameters:

Name Type Description Default
yaml_file str | Path | dict

Path to YAML file or dict to print.

required
Source code in ultralytics/utils/__init__.py
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
@classmethod
def print(cls, yaml_file):
    """
    Pretty print YAML file or object to console.

    Args:
        yaml_file (str | Path | dict): Path to YAML file or dict to print.
    """
    instance = cls._get_instance()

    # Load file if path provided
    yaml_dict = cls.load(yaml_file) if isinstance(yaml_file, (str, Path)) else yaml_file

    # Use -1 for unlimited width in C implementation
    dump = instance.yaml.dump(yaml_dict, sort_keys=False, allow_unicode=True, width=-1, Dumper=instance.SafeDumper)

    LOGGER.info(f"Printing '{colorstr('bold', 'black', yaml_file)}'\n\n{dump}")

save classmethod

save(file='data.yaml', data=None, header='')

Save Python object as YAML file.

Parameters:

Name Type Description Default
file str | Path

Path to save YAML file.

'data.yaml'
data dict | None

Dict or compatible object to save.

None
header str

Optional string to add at file beginning.

''
Source code in ultralytics/utils/__init__.py
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
@classmethod
def save(cls, file="data.yaml", data=None, header=""):
    """
    Save Python object as YAML file.

    Args:
        file (str | Path): Path to save YAML file.
        data (dict | None): Dict or compatible object to save.
        header (str): Optional string to add at file beginning.
    """
    instance = cls._get_instance()
    if data is None:
        data = {}

    # Create parent directories if needed
    file = Path(file)
    file.parent.mkdir(parents=True, exist_ok=True)

    # Convert non-serializable objects to strings
    valid_types = int, float, str, bool, list, tuple, dict, type(None)
    for k, v in data.items():
        if not isinstance(v, valid_types):
            data[k] = str(v)

    # Write YAML file
    with open(file, "w", errors="ignore", encoding="utf-8") as f:
        if header:
            f.write(header)
        instance.yaml.dump(data, f, sort_keys=False, allow_unicode=True, Dumper=instance.SafeDumper)





ultralytics.utils.TryExcept

TryExcept(msg='', verbose=True)

Bases: ContextDecorator

Ultralytics TryExcept class for handling exceptions gracefully.

This class can be used as a decorator or context manager to catch exceptions and optionally print warning messages. It allows code to continue execution even when exceptions occur, which is useful for non-critical operations.

Attributes:

Name Type Description
msg str

Optional message to display when an exception occurs.

verbose bool

Whether to print the exception message.

Examples:

As a decorator:

>>> @TryExcept(msg="Error occurred in func", verbose=True)
>>> def func():
>>> # Function logic here
>>>     pass

As a context manager:

>>> with TryExcept(msg="Error occurred in block", verbose=True):
>>> # Code block here
>>>     pass
Source code in ultralytics/utils/__init__.py
1072
1073
1074
1075
def __init__(self, msg="", verbose=True):
    """Initialize TryExcept class with optional message and verbosity settings."""
    self.msg = msg
    self.verbose = verbose

__enter__

__enter__()

Execute when entering TryExcept context, initialize instance.

Source code in ultralytics/utils/__init__.py
1077
1078
1079
def __enter__(self):
    """Execute when entering TryExcept context, initialize instance."""
    pass

__exit__

__exit__(exc_type, value, traceback)

Define behavior when exiting a 'with' block, print error message if necessary.

Source code in ultralytics/utils/__init__.py
1081
1082
1083
1084
1085
def __exit__(self, exc_type, value, traceback):
    """Define behavior when exiting a 'with' block, print error message if necessary."""
    if self.verbose and value:
        LOGGER.warning(f"{self.msg}{': ' if self.msg else ''}{value}")
    return True





ultralytics.utils.Retry

Retry(times=3, delay=2)

Bases: ContextDecorator

Retry class for function execution with exponential backoff.

This decorator can be used to retry a function on exceptions, up to a specified number of times with an exponentially increasing delay between retries. It's useful for handling transient failures in network operations or other unreliable processes.

Attributes:

Name Type Description
times int

Maximum number of retry attempts.

delay int

Initial delay between retries in seconds.

Examples:

Example usage as a decorator:

>>> @Retry(times=3, delay=2)
>>> def test_func():
>>> # Replace with function logic that may raise exceptions
>>>     return True
Source code in ultralytics/utils/__init__.py
1108
1109
1110
1111
1112
def __init__(self, times=3, delay=2):
    """Initialize Retry class with specified number of retries and delay."""
    self.times = times
    self.delay = delay
    self._attempts = 0

__call__

__call__(func)

Decorator implementation for Retry with exponential backoff.

Source code in ultralytics/utils/__init__.py
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
def __call__(self, func):
    """Decorator implementation for Retry with exponential backoff."""

    def wrapped_func(*args, **kwargs):
        """Apply retries to the decorated function or method."""
        self._attempts = 0
        while self._attempts < self.times:
            try:
                return func(*args, **kwargs)
            except Exception as e:
                self._attempts += 1
                LOGGER.warning(f"Retry {self._attempts}/{self.times} failed: {e}")
                if self._attempts >= self.times:
                    raise e
                time.sleep(self.delay * (2**self._attempts))  # exponential backoff delay

    return wrapped_func





ultralytics.utils.JSONDict

JSONDict(file_path: Union[str, Path] = 'data.json')

Bases: dict

A dictionary-like class that provides JSON persistence for its contents.

This class extends the built-in dictionary to automatically save its contents to a JSON file whenever they are modified. It ensures thread-safe operations using a lock and handles JSON serialization of Path objects.

Attributes:

Name Type Description
file_path Path

The path to the JSON file used for persistence.

lock Lock

A lock object to ensure thread-safe operations.

Methods:

Name Description
_load

Load the data from the JSON file into the dictionary.

_save

Save the current state of the dictionary to the JSON file.

__setitem__

Store a key-value pair and persist it to disk.

__delitem__

Remove an item and update the persistent storage.

update

Update the dictionary and persist changes.

clear

Clear all entries and update the persistent storage.

Examples:

>>> json_dict = JSONDict("data.json")
>>> json_dict["key"] = "value"
>>> print(json_dict["key"])
value
>>> del json_dict["key"]
>>> json_dict.update({"new_key": "new_value"})
>>> json_dict.clear()
Source code in ultralytics/utils/__init__.py
1267
1268
1269
1270
1271
1272
def __init__(self, file_path: Union[str, Path] = "data.json"):
    """Initialize a JSONDict object with a specified file path for JSON persistence."""
    super().__init__()
    self.file_path = Path(file_path)
    self.lock = Lock()
    self._load()

__delitem__

__delitem__(key)

Remove an item and update the persistent storage.

Source code in ultralytics/utils/__init__.py
1307
1308
1309
1310
1311
def __delitem__(self, key):
    """Remove an item and update the persistent storage."""
    with self.lock:
        super().__delitem__(key)
        self._save()

__setitem__

__setitem__(key, value)

Store a key-value pair and persist to disk.

Source code in ultralytics/utils/__init__.py
1301
1302
1303
1304
1305
def __setitem__(self, key, value):
    """Store a key-value pair and persist to disk."""
    with self.lock:
        super().__setitem__(key, value)
        self._save()

__str__

__str__()

Return a pretty-printed JSON string representation of the dictionary.

Source code in ultralytics/utils/__init__.py
1313
1314
1315
1316
def __str__(self):
    """Return a pretty-printed JSON string representation of the dictionary."""
    contents = json.dumps(dict(self), indent=2, ensure_ascii=False, default=self._json_default)
    return f'JSONDict("{self.file_path}"):\n{contents}'

clear

clear()

Clear all entries and update the persistent storage.

Source code in ultralytics/utils/__init__.py
1324
1325
1326
1327
1328
def clear(self):
    """Clear all entries and update the persistent storage."""
    with self.lock:
        super().clear()
        self._save()

update

update(*args, **kwargs)

Update the dictionary and persist changes.

Source code in ultralytics/utils/__init__.py
1318
1319
1320
1321
1322
def update(self, *args, **kwargs):
    """Update the dictionary and persist changes."""
    with self.lock:
        super().update(*args, **kwargs)
        self._save()





ultralytics.utils.SettingsManager

SettingsManager(file=SETTINGS_FILE, version='0.0.6')

Bases: JSONDict

SettingsManager class for managing and persisting Ultralytics settings.

This class extends JSONDict to provide JSON persistence for settings, ensuring thread-safe operations and default values. It validates settings on initialization and provides methods to update or reset settings. The settings include directories for datasets, weights, and runs, as well as various integration flags.

Attributes:

Name Type Description
file Path

The path to the JSON file used for persistence.

version str

The version of the settings schema.

defaults dict

A dictionary containing default settings.

help_msg str

A help message for users on how to view and update settings.

Methods:

Name Description
_validate_settings

Validate the current settings and reset if necessary.

update

Update settings, validating keys and types.

reset

Reset the settings to default and save them.

Examples:

Initialize and update settings:

>>> settings = SettingsManager()
>>> settings.update(runs_dir="/new/runs/dir")
>>> print(settings["runs_dir"])
/new/runs/dir
Source code in ultralytics/utils/__init__.py
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
def __init__(self, file=SETTINGS_FILE, version="0.0.6"):
    """Initialize the SettingsManager with default settings and load user settings."""
    import hashlib
    import uuid

    from ultralytics.utils.torch_utils import torch_distributed_zero_first

    root = GIT_DIR or Path()
    datasets_root = (root.parent if GIT_DIR and is_dir_writeable(root.parent) else root).resolve()

    self.file = Path(file)
    self.version = version
    self.defaults = {
        "settings_version": version,  # Settings schema version
        "datasets_dir": str(datasets_root / "datasets"),  # Datasets directory
        "weights_dir": str(root / "weights"),  # Model weights directory
        "runs_dir": str(root / "runs"),  # Experiment runs directory
        "uuid": hashlib.sha256(str(uuid.getnode()).encode()).hexdigest(),  # SHA-256 anonymized UUID hash
        "sync": True,  # Enable synchronization
        "api_key": "",  # Ultralytics API Key
        "openai_api_key": "",  # OpenAI API Key
        "clearml": True,  # ClearML integration
        "comet": True,  # Comet integration
        "dvc": True,  # DVC integration
        "hub": True,  # Ultralytics HUB integration
        "mlflow": True,  # MLflow integration
        "neptune": True,  # Neptune integration
        "raytune": True,  # Ray Tune integration
        "tensorboard": False,  # TensorBoard logging
        "wandb": False,  # Weights & Biases logging
        "vscode_msg": True,  # VSCode message
        "openvino_msg": True,  # OpenVINO export on Intel CPU message
    }

    self.help_msg = (
        f"\nView Ultralytics Settings with 'yolo settings' or at '{self.file}'"
        "\nUpdate Settings with 'yolo settings key=value', i.e. 'yolo settings runs_dir=path/to/dir'. "
        "For help see https://docs.ultralytics.com/quickstart/#ultralytics-settings."
    )

    with torch_distributed_zero_first(LOCAL_RANK):
        super().__init__(self.file)

        if not self.file.exists() or not self:  # Check if file doesn't exist or is empty
            LOGGER.info(f"Creating new Ultralytics Settings v{version} file ✅ {self.help_msg}")
            self.reset()

        self._validate_settings()

__setitem__

__setitem__(key, value)

Update one key: value pair.

Source code in ultralytics/utils/__init__.py
1427
1428
1429
def __setitem__(self, key, value):
    """Update one key: value pair."""
    self.update({key: value})

reset

reset()

Reset the settings to default and save them.

Source code in ultralytics/utils/__init__.py
1446
1447
1448
1449
def reset(self):
    """Reset the settings to default and save them."""
    self.clear()
    self.update(self.defaults)

update

update(*args, **kwargs)

Update settings, validating keys and types.

Source code in ultralytics/utils/__init__.py
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
def update(self, *args, **kwargs):
    """Update settings, validating keys and types."""
    for arg in args:
        if isinstance(arg, dict):
            kwargs.update(arg)
    for k, v in kwargs.items():
        if k not in self.defaults:
            raise KeyError(f"No Ultralytics setting '{k}'. {self.help_msg}")
        t = type(self.defaults[k])
        if not isinstance(v, t):
            raise TypeError(
                f"Ultralytics setting '{k}' must be '{t.__name__}' type, not '{type(v).__name__}'. {self.help_msg}"
            )
    super().update(*args, **kwargs)





ultralytics.utils.plt_settings

plt_settings(rcparams=None, backend='Agg')

Decorator to temporarily set rc parameters and the backend for a plotting function.

Parameters:

Name Type Description Default
rcparams dict

Dictionary of rc parameters to set.

None
backend str

Name of the backend to use.

'Agg'

Returns:

Type Description
Callable

Decorated function with temporarily set rc parameters and backend.

Examples:

>>> @plt_settings({"font.size": 12})
>>> def plot_function():
...     plt.figure()
...     plt.plot([1, 2, 3])
...     plt.show()
>>> with plt_settings({"font.size": 12}):
...     plt.figure()
...     plt.plot([1, 2, 3])
...     plt.show()
Source code in ultralytics/utils/__init__.py
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
def plt_settings(rcparams=None, backend="Agg"):
    """
    Decorator to temporarily set rc parameters and the backend for a plotting function.

    Args:
        rcparams (dict, optional): Dictionary of rc parameters to set.
        backend (str, optional): Name of the backend to use.

    Returns:
        (Callable): Decorated function with temporarily set rc parameters and backend.

    Examples:
        >>> @plt_settings({"font.size": 12})
        >>> def plot_function():
        ...     plt.figure()
        ...     plt.plot([1, 2, 3])
        ...     plt.show()

        >>> with plt_settings({"font.size": 12}):
        ...     plt.figure()
        ...     plt.plot([1, 2, 3])
        ...     plt.show()
    """
    if rcparams is None:
        rcparams = {"font.size": 11}

    def decorator(func):
        """Decorator to apply temporary rc parameters and backend to a function."""

        def wrapper(*args, **kwargs):
            """Set rc parameters and backend, call the original function, and restore the settings."""
            import matplotlib.pyplot as plt  # scope for faster 'import ultralytics'

            original_backend = plt.get_backend()
            switch = backend.lower() != original_backend.lower()
            if switch:
                plt.close("all")  # auto-close()ing of figures upon backend switching is deprecated since 3.8
                plt.switch_backend(backend)

            # Plot with backend and always revert to original backend
            try:
                with plt.rc_context(rcparams):
                    result = func(*args, **kwargs)
            finally:
                if switch:
                    plt.close("all")
                    plt.switch_backend(original_backend)
            return result

        return wrapper

    return decorator





ultralytics.utils.set_logging

set_logging(name='LOGGING_NAME', verbose=True)

Set up logging with UTF-8 encoding and configurable verbosity.

This function configures logging for the Ultralytics library, setting the appropriate logging level and formatter based on the verbosity flag and the current process rank. It handles special cases for Windows environments where UTF-8 encoding might not be the default.

Parameters:

Name Type Description Default
name str

Name of the logger.

'LOGGING_NAME'
verbose bool

Flag to set logging level to INFO if True, ERROR otherwise.

True

Returns:

Type Description
Logger

Configured logger object.

Examples:

>>> set_logging(name="ultralytics", verbose=True)
>>> logger = logging.getLogger("ultralytics")
>>> logger.info("This is an info message")
Notes
  • On Windows, this function attempts to reconfigure stdout to use UTF-8 encoding if possible.
  • If reconfiguration is not possible, it falls back to a custom formatter that handles non-UTF-8 environments.
  • The function sets up a StreamHandler with the appropriate formatter and level.
  • The logger's propagate flag is set to False to prevent duplicate logging in parent loggers.
Source code in ultralytics/utils/__init__.py
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
def set_logging(name="LOGGING_NAME", verbose=True):
    """
    Set up logging with UTF-8 encoding and configurable verbosity.

    This function configures logging for the Ultralytics library, setting the appropriate logging level and
    formatter based on the verbosity flag and the current process rank. It handles special cases for Windows
    environments where UTF-8 encoding might not be the default.

    Args:
        name (str): Name of the logger.
        verbose (bool): Flag to set logging level to INFO if True, ERROR otherwise.

    Returns:
        (logging.Logger): Configured logger object.

    Examples:
        >>> set_logging(name="ultralytics", verbose=True)
        >>> logger = logging.getLogger("ultralytics")
        >>> logger.info("This is an info message")

    Notes:
        - On Windows, this function attempts to reconfigure stdout to use UTF-8 encoding if possible.
        - If reconfiguration is not possible, it falls back to a custom formatter that handles non-UTF-8 environments.
        - The function sets up a StreamHandler with the appropriate formatter and level.
        - The logger's propagate flag is set to False to prevent duplicate logging in parent loggers.
    """
    level = logging.INFO if verbose and RANK in {-1, 0} else logging.ERROR  # rank in world for Multi-GPU trainings

    class PrefixFormatter(logging.Formatter):
        def format(self, record):
            """Format log records with prefixes based on level."""
            # Apply prefixes based on log level
            if record.levelno == logging.WARNING:
                prefix = "WARNING" if WINDOWS else "WARNING ⚠️"
                record.msg = f"{prefix} {record.msg}"
            elif record.levelno == logging.ERROR:
                prefix = "ERROR" if WINDOWS else "ERROR ❌"
                record.msg = f"{prefix} {record.msg}"

            # Handle emojis in message based on platform
            formatted_message = super().format(record)
            return emojis(formatted_message)

    formatter = PrefixFormatter("%(message)s")

    # Handle Windows UTF-8 encoding issues
    if WINDOWS and hasattr(sys.stdout, "encoding") and sys.stdout.encoding != "utf-8":
        with contextlib.suppress(Exception):
            # Attempt to reconfigure stdout to use UTF-8 encoding if possible
            if hasattr(sys.stdout, "reconfigure"):
                sys.stdout.reconfigure(encoding="utf-8")
            # For environments where reconfigure is not available, wrap stdout in a TextIOWrapper
            elif hasattr(sys.stdout, "buffer"):
                import io

                sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")

    # Create and configure the StreamHandler with the appropriate formatter and level
    stream_handler = logging.StreamHandler(sys.stdout)
    stream_handler.setFormatter(formatter)
    stream_handler.setLevel(level)

    # Set up the logger
    logger = logging.getLogger(name)
    logger.setLevel(level)
    logger.addHandler(stream_handler)
    logger.propagate = False
    return logger





ultralytics.utils.emojis

emojis(string='')

Return platform-dependent emoji-safe version of string.

Source code in ultralytics/utils/__init__.py
462
463
464
def emojis(string=""):
    """Return platform-dependent emoji-safe version of string."""
    return string.encode().decode("ascii", "ignore") if WINDOWS else string





ultralytics.utils.read_device_model

read_device_model() -> str

Read the device model information from the system and cache it for quick access.

Returns:

Type Description
str

Kernel release information.

Source code in ultralytics/utils/__init__.py
641
642
643
644
645
646
647
648
def read_device_model() -> str:
    """
    Read the device model information from the system and cache it for quick access.

    Returns:
        (str): Kernel release information.
    """
    return platform.release().lower()





ultralytics.utils.is_ubuntu

is_ubuntu() -> bool

Check if the OS is Ubuntu.

Returns:

Type Description
bool

True if OS is Ubuntu, False otherwise.

Source code in ultralytics/utils/__init__.py
651
652
653
654
655
656
657
658
659
660
661
662
def is_ubuntu() -> bool:
    """
    Check if the OS is Ubuntu.

    Returns:
        (bool): True if OS is Ubuntu, False otherwise.
    """
    try:
        with open("/etc/os-release") as f:
            return "ID=ubuntu" in f.read()
    except FileNotFoundError:
        return False





ultralytics.utils.is_colab

is_colab()

Check if the current script is running inside a Google Colab notebook.

Returns:

Type Description
bool

True if running inside a Colab notebook, False otherwise.

Source code in ultralytics/utils/__init__.py
665
666
667
668
669
670
671
672
def is_colab():
    """
    Check if the current script is running inside a Google Colab notebook.

    Returns:
        (bool): True if running inside a Colab notebook, False otherwise.
    """
    return "COLAB_RELEASE_TAG" in os.environ or "COLAB_BACKEND_VERSION" in os.environ





ultralytics.utils.is_kaggle

is_kaggle()

Check if the current script is running inside a Kaggle kernel.

Returns:

Type Description
bool

True if running inside a Kaggle kernel, False otherwise.

Source code in ultralytics/utils/__init__.py
675
676
677
678
679
680
681
682
def is_kaggle():
    """
    Check if the current script is running inside a Kaggle kernel.

    Returns:
        (bool): True if running inside a Kaggle kernel, False otherwise.
    """
    return os.environ.get("PWD") == "/kaggle/working" and os.environ.get("KAGGLE_URL_BASE") == "https://www.kaggle.com"





ultralytics.utils.is_jupyter

is_jupyter()

Check if the current script is running inside a Jupyter Notebook.

Returns:

Type Description
bool

True if running inside a Jupyter Notebook, False otherwise.

Notes
  • Only works on Colab and Kaggle, other environments like Jupyterlab and Paperspace are not reliably detectable.
  • "get_ipython" in globals() method suffers false positives when IPython package installed manually.
Source code in ultralytics/utils/__init__.py
685
686
687
688
689
690
691
692
693
694
695
696
def is_jupyter():
    """
    Check if the current script is running inside a Jupyter Notebook.

    Returns:
        (bool): True if running inside a Jupyter Notebook, False otherwise.

    Notes:
        - Only works on Colab and Kaggle, other environments like Jupyterlab and Paperspace are not reliably detectable.
        - "get_ipython" in globals() method suffers false positives when IPython package installed manually.
    """
    return IS_COLAB or IS_KAGGLE





ultralytics.utils.is_runpod

is_runpod()

Check if the current script is running inside a RunPod container.

Returns:

Type Description
bool

True if running in RunPod, False otherwise.

Source code in ultralytics/utils/__init__.py
699
700
701
702
703
704
705
706
def is_runpod():
    """
    Check if the current script is running inside a RunPod container.

    Returns:
        (bool): True if running in RunPod, False otherwise.
    """
    return "RUNPOD_POD_ID" in os.environ





ultralytics.utils.is_docker

is_docker() -> bool

Determine if the script is running inside a Docker container.

Returns:

Type Description
bool

True if the script is running inside a Docker container, False otherwise.

Source code in ultralytics/utils/__init__.py
709
710
711
712
713
714
715
716
717
718
719
def is_docker() -> bool:
    """
    Determine if the script is running inside a Docker container.

    Returns:
        (bool): True if the script is running inside a Docker container, False otherwise.
    """
    try:
        return os.path.exists("/.dockerenv")
    except Exception:
        return False





ultralytics.utils.is_raspberrypi

is_raspberrypi() -> bool

Determine if the Python environment is running on a Raspberry Pi.

Returns:

Type Description
bool

True if running on a Raspberry Pi, False otherwise.

Source code in ultralytics/utils/__init__.py
722
723
724
725
726
727
728
729
def is_raspberrypi() -> bool:
    """
    Determine if the Python environment is running on a Raspberry Pi.

    Returns:
        (bool): True if running on a Raspberry Pi, False otherwise.
    """
    return "rpi" in DEVICE_MODEL





ultralytics.utils.is_jetson cached

is_jetson(jetpack=None) -> bool

Determine if the Python environment is running on an NVIDIA Jetson device.

Parameters:

Name Type Description Default
jetpack int | None

If specified, check for specific JetPack version (4, 5, 6).

None

Returns:

Type Description
bool

True if running on an NVIDIA Jetson device, False otherwise.

Source code in ultralytics/utils/__init__.py
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
@lru_cache(maxsize=3)
def is_jetson(jetpack=None) -> bool:
    """
    Determine if the Python environment is running on an NVIDIA Jetson device.

    Args:
        jetpack (int | None): If specified, check for specific JetPack version (4, 5, 6).

    Returns:
        (bool): True if running on an NVIDIA Jetson device, False otherwise.
    """
    if jetson := ("tegra" in DEVICE_MODEL):
        if jetpack:
            try:
                content = open("/etc/nv_tegra_release").read()
                version_map = {4: "R32", 5: "R35", 6: "R36"}  # JetPack to L4T major version mapping
                return jetpack in version_map and version_map[jetpack] in content
            except Exception:
                return False
    return jetson





ultralytics.utils.is_online

is_online() -> bool

Fast online check using DNS (v4/v6) resolution (Cloudflare + Google).

Returns:

Type Description
bool

True if connection is successful, False otherwise.

Source code in ultralytics/utils/__init__.py
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
def is_online() -> bool:
    """
    Fast online check using DNS (v4/v6) resolution (Cloudflare + Google).

    Returns:
        (bool): True if connection is successful, False otherwise.
    """
    if str(os.getenv("YOLO_OFFLINE", "")).lower() == "true":
        return False

    for host in ("one.one.one.one", "dns.google"):
        try:
            socket.getaddrinfo(host, 0, socket.AF_UNSPEC, 0, 0, socket.AI_ADDRCONFIG)
            return True
        except OSError:
            continue
    return False





ultralytics.utils.is_pip_package

is_pip_package(filepath: str = __name__) -> bool

Determine if the file at the given filepath is part of a pip package.

Parameters:

Name Type Description Default
filepath str

The filepath to check.

__name__

Returns:

Type Description
bool

True if the file is part of a pip package, False otherwise.

Source code in ultralytics/utils/__init__.py
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
def is_pip_package(filepath: str = __name__) -> bool:
    """
    Determine if the file at the given filepath is part of a pip package.

    Args:
        filepath (str): The filepath to check.

    Returns:
        (bool): True if the file is part of a pip package, False otherwise.
    """
    import importlib.util

    # Get the spec for the module
    spec = importlib.util.find_spec(filepath)

    # Return whether the spec is not None and the origin is not None (indicating it is a package)
    return spec is not None and spec.origin is not None





ultralytics.utils.is_dir_writeable

is_dir_writeable(dir_path: Union[str, Path]) -> bool

Check if a directory is writeable.

Parameters:

Name Type Description Default
dir_path str | Path

The path to the directory.

required

Returns:

Type Description
bool

True if the directory is writeable, False otherwise.

Source code in ultralytics/utils/__init__.py
792
793
794
795
796
797
798
799
800
801
802
def is_dir_writeable(dir_path: Union[str, Path]) -> bool:
    """
    Check if a directory is writeable.

    Args:
        dir_path (str | Path): The path to the directory.

    Returns:
        (bool): True if the directory is writeable, False otherwise.
    """
    return os.access(str(dir_path), os.W_OK)





ultralytics.utils.is_pytest_running

is_pytest_running()

Determine whether pytest is currently running or not.

Returns:

Type Description
bool

True if pytest is running, False otherwise.

Source code in ultralytics/utils/__init__.py
805
806
807
808
809
810
811
812
def is_pytest_running():
    """
    Determine whether pytest is currently running or not.

    Returns:
        (bool): True if pytest is running, False otherwise.
    """
    return ("PYTEST_CURRENT_TEST" in os.environ) or ("pytest" in sys.modules) or ("pytest" in Path(ARGV[0]).stem)





ultralytics.utils.is_github_action_running

is_github_action_running() -> bool

Determine if the current environment is a GitHub Actions runner.

Returns:

Type Description
bool

True if the current environment is a GitHub Actions runner, False otherwise.

Source code in ultralytics/utils/__init__.py
815
816
817
818
819
820
821
822
def is_github_action_running() -> bool:
    """
    Determine if the current environment is a GitHub Actions runner.

    Returns:
        (bool): True if the current environment is a GitHub Actions runner, False otherwise.
    """
    return "GITHUB_ACTIONS" in os.environ and "GITHUB_WORKFLOW" in os.environ and "RUNNER_OS" in os.environ





ultralytics.utils.get_git_dir

get_git_dir()

Determine whether the current file is part of a git repository and if so, return the repository root directory.

Returns:

Type Description
Path | None

Git root directory if found or None if not found.

Source code in ultralytics/utils/__init__.py
825
826
827
828
829
830
831
832
833
834
def get_git_dir():
    """
    Determine whether the current file is part of a git repository and if so, return the repository root directory.

    Returns:
        (Path | None): Git root directory if found or None if not found.
    """
    for d in Path(__file__).parents:
        if (d / ".git").is_dir():
            return d





ultralytics.utils.is_git_dir

is_git_dir()

Determine whether the current file is part of a git repository.

Returns:

Type Description
bool

True if current file is part of a git repository.

Source code in ultralytics/utils/__init__.py
837
838
839
840
841
842
843
844
def is_git_dir():
    """
    Determine whether the current file is part of a git repository.

    Returns:
        (bool): True if current file is part of a git repository.
    """
    return GIT_DIR is not None





ultralytics.utils.get_git_origin_url cached

get_git_origin_url()

Retrieve the origin URL of a git repository.

Returns:

Type Description
str | None

The origin URL of the git repository or None if not git directory.

Source code in ultralytics/utils/__init__.py
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
@lru_cache(maxsize=1)
def get_git_origin_url():
    """
    Retrieve the origin URL of a git repository.

    Returns:
        (str | None): The origin URL of the git repository or None if not git directory.
    """
    if IS_GIT_DIR:
        try:
            return subprocess.check_output(
                ["git", "config", "--get", "remote.origin.url"], stderr=subprocess.DEVNULL, text=True
            ).strip()
        except subprocess.CalledProcessError:
            return None





ultralytics.utils.get_git_branch cached

get_git_branch()

Return the current git branch name. If not in a git repository, return None.

Returns:

Type Description
str | None

The current git branch name or None if not a git directory.

Source code in ultralytics/utils/__init__.py
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
@lru_cache(maxsize=1)
def get_git_branch():
    """
    Return the current git branch name. If not in a git repository, return None.

    Returns:
        (str | None): The current git branch name or None if not a git directory.
    """
    if IS_GIT_DIR:
        try:
            return subprocess.check_output(
                ["git", "rev-parse", "--abbrev-ref", "HEAD"], stderr=subprocess.DEVNULL, text=True
            ).strip()
        except subprocess.CalledProcessError:
            return None





ultralytics.utils.get_git_commit cached

get_git_commit()

Return the current git commit hash. If not in a git repository, return None.

Returns:

Type Description
str | None

The current git commit hash or None if not a git directory.

Source code in ultralytics/utils/__init__.py
881
882
883
884
885
886
887
888
889
890
891
892
893
@lru_cache(maxsize=1)
def get_git_commit():
    """
    Return the current git commit hash. If not in a git repository, return None.

    Returns:
        (str | None): The current git commit hash or None if not a git directory.
    """
    if IS_GIT_DIR:
        try:
            return subprocess.check_output(["git", "rev-parse", "HEAD"], stderr=subprocess.DEVNULL, text=True).strip()
        except subprocess.CalledProcessError:
            return None





ultralytics.utils.get_default_args

get_default_args(func)

Return a dictionary of default arguments for a function.

Parameters:

Name Type Description Default
func callable

The function to inspect.

required

Returns:

Type Description
dict

A dictionary where each key is a parameter name, and each value is the default value of that parameter.

Source code in ultralytics/utils/__init__.py
896
897
898
899
900
901
902
903
904
905
906
907
def get_default_args(func):
    """
    Return a dictionary of default arguments for a function.

    Args:
        func (callable): The function to inspect.

    Returns:
        (dict): A dictionary where each key is a parameter name, and each value is the default value of that parameter.
    """
    signature = inspect.signature(func)
    return {k: v.default for k, v in signature.parameters.items() if v.default is not inspect.Parameter.empty}





ultralytics.utils.get_ubuntu_version

get_ubuntu_version()

Retrieve the Ubuntu version if the OS is Ubuntu.

Returns:

Type Description
str

Ubuntu version or None if not an Ubuntu OS.

Source code in ultralytics/utils/__init__.py
910
911
912
913
914
915
916
917
918
919
920
921
922
def get_ubuntu_version():
    """
    Retrieve the Ubuntu version if the OS is Ubuntu.

    Returns:
        (str): Ubuntu version or None if not an Ubuntu OS.
    """
    if is_ubuntu():
        try:
            with open("/etc/os-release") as f:
                return re.search(r'VERSION_ID="(\d+\.\d+)"', f.read())[1]
        except (FileNotFoundError, AttributeError):
            return None





ultralytics.utils.get_user_config_dir

get_user_config_dir(sub_dir='Ultralytics')

Return the appropriate config directory based on the environment operating system.

Parameters:

Name Type Description Default
sub_dir str

The name of the subdirectory to create.

'Ultralytics'

Returns:

Type Description
Path

The path to the user config directory.

Source code in ultralytics/utils/__init__.py
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
def get_user_config_dir(sub_dir="Ultralytics"):
    """
    Return the appropriate config directory based on the environment operating system.

    Args:
        sub_dir (str): The name of the subdirectory to create.

    Returns:
        (Path): The path to the user config directory.
    """
    if WINDOWS:
        path = Path.home() / "AppData" / "Roaming" / sub_dir
    elif MACOS:  # macOS
        path = Path.home() / "Library" / "Application Support" / sub_dir
    elif LINUX:
        path = Path.home() / ".config" / sub_dir
    else:
        raise ValueError(f"Unsupported operating system: {platform.system()}")

    # GCP and AWS lambda fix, only /tmp is writeable
    if not is_dir_writeable(path.parent):
        LOGGER.warning(
            f"user config directory '{path}' is not writeable, defaulting to '/tmp' or CWD. "
            "Alternatively you can define a YOLO_CONFIG_DIR environment variable for this path."
        )
        path = Path("/tmp") / sub_dir if is_dir_writeable("/tmp") else Path().cwd() / sub_dir

    # Create the subdirectory if it does not exist
    path.mkdir(parents=True, exist_ok=True)

    return path





ultralytics.utils.colorstr

colorstr(*input)

Color a string based on the provided color and style arguments using ANSI escape codes.

This function can be called in two ways
  • colorstr('color', 'style', 'your string')
  • colorstr('your string')

In the second form, 'blue' and 'bold' will be applied by default.

Parameters:

Name Type Description Default
*input str | Path

A sequence of strings where the first n-1 strings are color and style arguments, and the last string is the one to be colored.

()

Returns:

Type Description
str

The input string wrapped with ANSI escape codes for the specified color and style.

Notes

Supported Colors and Styles: - Basic Colors: 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white' - Bright Colors: 'bright_black', 'bright_red', 'bright_green', 'bright_yellow', 'bright_blue', 'bright_magenta', 'bright_cyan', 'bright_white' - Misc: 'end', 'bold', 'underline'

Examples:

>>> colorstr("blue", "bold", "hello world")
>>> "\033[34m\033[1mhello world\033[0m"
References

https://en.wikipedia.org/wiki/ANSI_escape_code

Source code in ultralytics/utils/__init__.py
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
def colorstr(*input):
    r"""
    Color a string based on the provided color and style arguments using ANSI escape codes.

    This function can be called in two ways:
        - colorstr('color', 'style', 'your string')
        - colorstr('your string')

    In the second form, 'blue' and 'bold' will be applied by default.

    Args:
        *input (str | Path): A sequence of strings where the first n-1 strings are color and style arguments,
                      and the last string is the one to be colored.

    Returns:
        (str): The input string wrapped with ANSI escape codes for the specified color and style.

    Notes:
        Supported Colors and Styles:
        - Basic Colors: 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'
        - Bright Colors: 'bright_black', 'bright_red', 'bright_green', 'bright_yellow',
                       'bright_blue', 'bright_magenta', 'bright_cyan', 'bright_white'
        - Misc: 'end', 'bold', 'underline'

    Examples:
        >>> colorstr("blue", "bold", "hello world")
        >>> "\033[34m\033[1mhello world\033[0m"

    References:
        https://en.wikipedia.org/wiki/ANSI_escape_code
    """
    *args, string = input if len(input) > 1 else ("blue", "bold", input[0])  # color arguments, string
    colors = {
        "black": "\033[30m",  # basic colors
        "red": "\033[31m",
        "green": "\033[32m",
        "yellow": "\033[33m",
        "blue": "\033[34m",
        "magenta": "\033[35m",
        "cyan": "\033[36m",
        "white": "\033[37m",
        "bright_black": "\033[90m",  # bright colors
        "bright_red": "\033[91m",
        "bright_green": "\033[92m",
        "bright_yellow": "\033[93m",
        "bright_blue": "\033[94m",
        "bright_magenta": "\033[95m",
        "bright_cyan": "\033[96m",
        "bright_white": "\033[97m",
        "end": "\033[0m",  # misc
        "bold": "\033[1m",
        "underline": "\033[4m",
    }
    return "".join(colors[x] for x in args) + f"{string}" + colors["end"]





ultralytics.utils.remove_colorstr

remove_colorstr(input_string)

Remove ANSI escape codes from a string, effectively un-coloring it.

Parameters:

Name Type Description Default
input_string str

The string to remove color and style from.

required

Returns:

Type Description
str

A new string with all ANSI escape codes removed.

Examples:

>>> remove_colorstr(colorstr("blue", "bold", "hello world"))
>>> "hello world"
Source code in ultralytics/utils/__init__.py
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
def remove_colorstr(input_string):
    """
    Remove ANSI escape codes from a string, effectively un-coloring it.

    Args:
        input_string (str): The string to remove color and style from.

    Returns:
        (str): A new string with all ANSI escape codes removed.

    Examples:
        >>> remove_colorstr(colorstr("blue", "bold", "hello world"))
        >>> "hello world"
    """
    ansi_escape = re.compile(r"\x1B\[[0-9;]*[A-Za-z]")
    return ansi_escape.sub("", input_string)





ultralytics.utils.threaded

threaded(func)

Multi-thread a target function by default and return the thread or function result.

This decorator provides flexible execution of the target function, either in a separate thread or synchronously. By default, the function runs in a thread, but this can be controlled via the 'threaded=False' keyword argument which is removed from kwargs before calling the function.

Parameters:

Name Type Description Default
func callable

The function to be potentially executed in a separate thread.

required

Returns:

Type Description
callable

A wrapper function that either returns a daemon thread or the direct function result.

Examples:

>>> @threaded
... def process_data(data):
...     return data
>>>
>>> thread = process_data(my_data)  # Runs in background thread
>>> result = process_data(my_data, threaded=False)  # Runs synchronously, returns function result
Source code in ultralytics/utils/__init__.py
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
def threaded(func):
    """
    Multi-thread a target function by default and return the thread or function result.

    This decorator provides flexible execution of the target function, either in a separate thread or synchronously.
    By default, the function runs in a thread, but this can be controlled via the 'threaded=False' keyword argument
    which is removed from kwargs before calling the function.

    Args:
        func (callable): The function to be potentially executed in a separate thread.

    Returns:
        (callable): A wrapper function that either returns a daemon thread or the direct function result.

    Examples:
        >>> @threaded
        ... def process_data(data):
        ...     return data
        >>>
        >>> thread = process_data(my_data)  # Runs in background thread
        >>> result = process_data(my_data, threaded=False)  # Runs synchronously, returns function result
    """

    def wrapper(*args, **kwargs):
        """Multi-thread a given function based on 'threaded' kwarg and return the thread or function result."""
        if kwargs.pop("threaded", True):  # run in thread
            thread = threading.Thread(target=func, args=args, kwargs=kwargs, daemon=True)
            thread.start()
            return thread
        else:
            return func(*args, **kwargs)

    return wrapper





ultralytics.utils.set_sentry

set_sentry()

Initialize the Sentry SDK for error tracking and reporting.

Only used if sentry_sdk package is installed and sync=True in settings. Run 'yolo settings' to see and update settings.

Conditions required to send errors (ALL conditions must be met or no errors will be reported): - sentry_sdk package is installed - sync=True in YOLO settings - pytest is not running - running in a pip package installation - running in a non-git directory - running with rank -1 or 0 - online environment - CLI used to run package (checked with 'yolo' as the name of the main CLI command)

Source code in ultralytics/utils/__init__.py
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
def set_sentry():
    """
    Initialize the Sentry SDK for error tracking and reporting.

    Only used if sentry_sdk package is installed and sync=True in settings. Run 'yolo settings' to see and update
    settings.

    Conditions required to send errors (ALL conditions must be met or no errors will be reported):
        - sentry_sdk package is installed
        - sync=True in YOLO settings
        - pytest is not running
        - running in a pip package installation
        - running in a non-git directory
        - running with rank -1 or 0
        - online environment
        - CLI used to run package (checked with 'yolo' as the name of the main CLI command)
    """
    if (
        not SETTINGS["sync"]
        or RANK not in {-1, 0}
        or Path(ARGV[0]).name != "yolo"
        or TESTS_RUNNING
        or not ONLINE
        or not IS_PIP_PACKAGE
        or IS_GIT_DIR
    ):
        return
    # If sentry_sdk package is not installed then return and do not use Sentry
    try:
        import sentry_sdk  # noqa
    except ImportError:
        return

    def before_send(event, hint):
        """
        Modify the event before sending it to Sentry based on specific exception types and messages.

        Args:
            event (dict): The event dictionary containing information about the error.
            hint (dict): A dictionary containing additional information about the error.

        Returns:
            (dict | None): The modified event or None if the event should not be sent to Sentry.
        """
        if "exc_info" in hint:
            exc_type, exc_value, _ = hint["exc_info"]
            if exc_type in {KeyboardInterrupt, FileNotFoundError} or "out of memory" in str(exc_value):
                return None  # do not send event

        event["tags"] = {
            "sys_argv": ARGV[0],
            "sys_argv_name": Path(ARGV[0]).name,
            "install": "git" if IS_GIT_DIR else "pip" if IS_PIP_PACKAGE else "other",
            "os": ENVIRONMENT,
        }
        return event

    sentry_sdk.init(
        dsn="https://888e5a0778212e1d0314c37d4b9aae5d@o4504521589325824.ingest.us.sentry.io/4504521592406016",
        debug=False,
        auto_enabling_integrations=False,
        traces_sample_rate=1.0,
        release=__version__,
        environment="runpod" if is_runpod() else "production",
        before_send=before_send,
        ignore_errors=[KeyboardInterrupt, FileNotFoundError],
    )
    sentry_sdk.set_user({"id": SETTINGS["uuid"]})  # SHA-256 anonymized UUID hash





ultralytics.utils.deprecation_warn

deprecation_warn(arg, new_arg=None)

Issue a deprecation warning when a deprecated argument is used, suggesting an updated argument.

Source code in ultralytics/utils/__init__.py
1452
1453
1454
1455
1456
1457
def deprecation_warn(arg, new_arg=None):
    """Issue a deprecation warning when a deprecated argument is used, suggesting an updated argument."""
    msg = f"'{arg}' is deprecated and will be removed in in the future."
    if new_arg is not None:
        msg += f" Use '{new_arg}' instead."
    LOGGER.warning(msg)





ultralytics.utils.clean_url

clean_url(url)

Strip auth from URL, i.e. https://url.com/file.txt?auth -> https://url.com/file.txt.

Source code in ultralytics/utils/__init__.py
1460
1461
1462
1463
def clean_url(url):
    """Strip auth from URL, i.e. https://url.com/file.txt?auth -> https://url.com/file.txt."""
    url = Path(url).as_posix().replace(":/", "://")  # Pathlib turns :// -> :/, as_posix() for Windows
    return unquote(url).split("?", 1)[0]  # '%2F' to '/', split https://url.com/file.txt?auth





ultralytics.utils.url2file

url2file(url)

Convert URL to filename, i.e. https://url.com/file.txt?auth -> file.txt.

Source code in ultralytics/utils/__init__.py
1466
1467
1468
def url2file(url):
    """Convert URL to filename, i.e. https://url.com/file.txt?auth -> file.txt."""
    return Path(clean_url(url)).name





ultralytics.utils.vscode_msg

vscode_msg(ext='ultralytics.ultralytics-snippets') -> str

Display a message to install Ultralytics-Snippets for VS Code if not already installed.

Source code in ultralytics/utils/__init__.py
1471
1472
1473
1474
1475
1476
1477
def vscode_msg(ext="ultralytics.ultralytics-snippets") -> str:
    """Display a message to install Ultralytics-Snippets for VS Code if not already installed."""
    path = (USER_CONFIG_DIR.parents[2] if WINDOWS else USER_CONFIG_DIR.parents[1]) / ".vscode/extensions"
    obs_file = path / ".obsolete"  # file tracks uninstalled extensions, while source directory remains
    installed = any(path.glob(f"{ext}*")) and ext not in (obs_file.read_text("utf-8") if obs_file.exists() else "")
    url = "https://docs.ultralytics.com/integrations/vscode"
    return "" if installed else f"{colorstr('VS Code:')} view Ultralytics VS Code Extension ⚡ at {url}"





📅 Created 1 year ago ✏️ Updated 0 days ago