Reference for ultralytics/utils/checks.py
Note
This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/utils/checks.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!
ultralytics.utils.checks.parse_requirements
parse_requirements(file_path=ROOT.parent / 'requirements.txt', package='')
Parse a requirements.txt file, ignoring lines that start with '#' and any text after '#'.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
file_path
|
Path
|
Path to the requirements.txt file. |
parent / 'requirements.txt'
|
package
|
str
|
Python package to use instead of requirements.txt file. |
''
|
Returns:
Name | Type | Description |
---|---|---|
requirements |
List[SimpleNamespace]
|
List of parsed requirements as SimpleNamespace objects with |
Examples:
>>> from ultralytics.utils.checks import parse_requirements
>>> parse_requirements(package="ultralytics")
Source code in ultralytics/utils/checks.py
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 |
|
ultralytics.utils.checks.parse_version
cached
parse_version(version='0.0.0') -> tuple
Convert a version string to a tuple of integers, ignoring any extra non-numeric string attached to the version.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
version
|
str
|
Version string, i.e. '2.0.1+cpu' |
'0.0.0'
|
Returns:
Type | Description |
---|---|
tuple
|
Tuple of integers representing the numeric part of the version, i.e. (2, 0, 1) |
Source code in ultralytics/utils/checks.py
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 |
|
ultralytics.utils.checks.is_ascii
is_ascii(s) -> bool
Check if a string is composed of only ASCII characters.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
s
|
str | list | tuple | dict
|
Input to be checked (all are converted to string for checking). |
required |
Returns:
Type | Description |
---|---|
bool
|
True if the string is composed only of ASCII characters, False otherwise. |
Source code in ultralytics/utils/checks.py
103 104 105 106 107 108 109 110 111 112 113 |
|
ultralytics.utils.checks.check_imgsz
check_imgsz(imgsz, stride=32, min_dim=1, max_dim=2, floor=0)
Verify image size is a multiple of the given stride in each dimension. If the image size is not a multiple of the stride, update it to the nearest multiple of the stride that is greater than or equal to the given floor value.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
imgsz
|
int | List[int]
|
Image size. |
required |
stride
|
int
|
Stride value. |
32
|
min_dim
|
int
|
Minimum number of dimensions. |
1
|
max_dim
|
int
|
Maximum number of dimensions. |
2
|
floor
|
int
|
Minimum allowed value for image size. |
0
|
Returns:
Type | Description |
---|---|
List[int] | int
|
Updated image size. |
Source code in ultralytics/utils/checks.py
116 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 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 |
|
ultralytics.utils.checks.check_uv
cached
check_uv()
Check if uv package manager is installed and can run successfully.
Source code in ultralytics/utils/checks.py
170 171 172 173 174 175 176 |
|
ultralytics.utils.checks.check_version
cached
check_version(
current: str = "0.0.0",
required: str = "0.0.0",
name: str = "version",
hard: bool = False,
verbose: bool = False,
msg: str = "",
) -> bool
Check current version against the required version or range.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
current
|
str
|
Current version or package name to get version from. |
'0.0.0'
|
required
|
str
|
Required version or range (in pip-style format). |
'0.0.0'
|
name
|
str
|
Name to be used in warning message. |
'version'
|
hard
|
bool
|
If True, raise an AssertionError if the requirement is not met. |
False
|
verbose
|
bool
|
If True, print warning message if requirement is not met. |
False
|
msg
|
str
|
Extra message to display if verbose. |
''
|
Returns:
Type | Description |
---|---|
bool
|
True if requirement is met, False otherwise. |
Examples:
Check if current version is exactly 22.04
>>> check_version(current="22.04", required="==22.04")
Check if current version is greater than or equal to 22.04
>>> check_version(current="22.10", required="22.04") # assumes '>=' inequality if none passed
Check if current version is less than or equal to 22.04
>>> check_version(current="22.04", required="<=22.04")
Check if current version is between 20.04 (inclusive) and 22.04 (exclusive)
>>> check_version(current="21.10", required=">20.04,<22.04")
Source code in ultralytics/utils/checks.py
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 |
|
ultralytics.utils.checks.check_latest_pypi_version
check_latest_pypi_version(package_name='ultralytics')
Return the latest version of a PyPI package without downloading or installing it.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
package_name
|
str
|
The name of the package to find the latest version for. |
'ultralytics'
|
Returns:
Type | Description |
---|---|
str
|
The latest version of the package. |
Source code in ultralytics/utils/checks.py
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 |
|
ultralytics.utils.checks.check_pip_update_available
check_pip_update_available()
Check if a new version of the ultralytics package is available on PyPI.
Returns:
Type | Description |
---|---|
bool
|
True if an update is available, False otherwise. |
Source code in ultralytics/utils/checks.py
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 |
|
ultralytics.utils.checks.check_font
cached
check_font(font='Arial.ttf')
Find font locally or download to user's configuration directory if it does not already exist.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
font
|
str
|
Path or name of font. |
'Arial.ttf'
|
Returns:
Type | Description |
---|---|
Path
|
Resolved font file path. |
Source code in ultralytics/utils/checks.py
312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 |
|
ultralytics.utils.checks.check_python
check_python(
minimum: str = "3.8.0", hard: bool = True, verbose: bool = False
) -> bool
Check current python version against the required minimum version.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
minimum
|
str
|
Required minimum version of python. |
'3.8.0'
|
hard
|
bool
|
If True, raise an AssertionError if the requirement is not met. |
True
|
verbose
|
bool
|
If True, print warning message if requirement is not met. |
False
|
Returns:
Type | Description |
---|---|
bool
|
Whether the installed Python version meets the minimum constraints. |
Source code in ultralytics/utils/checks.py
344 345 346 347 348 349 350 351 352 353 354 355 356 |
|
ultralytics.utils.checks.check_requirements
check_requirements(
requirements=ROOT.parent / "requirements.txt",
exclude=(),
install=True,
cmds="",
)
Check if installed dependencies meet Ultralytics YOLO models requirements and attempt to auto-update if needed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
requirements
|
Path | str | List[str]
|
Path to a requirements.txt file, a single package requirement as a string, or a list of package requirements as strings. |
parent / 'requirements.txt'
|
exclude
|
tuple
|
Tuple of package names to exclude from checking. |
()
|
install
|
bool
|
If True, attempt to auto-update packages that don't meet requirements. |
True
|
cmds
|
str
|
Additional commands to pass to the pip install command when auto-updating. |
''
|
Examples:
>>> from ultralytics.utils.checks import check_requirements
Check a requirements.txt file
>>> check_requirements("path/to/requirements.txt")
Check a single package
>>> check_requirements("ultralytics>=8.0.0")
Check multiple packages
>>> check_requirements(["numpy", "ultralytics>=8.0.0"])
Source code in ultralytics/utils/checks.py
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 384 385 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 |
|
ultralytics.utils.checks.check_torchvision
check_torchvision()
Check the installed versions of PyTorch and Torchvision to ensure they're compatible.
This function checks the installed versions of PyTorch and Torchvision, and warns if they're incompatible according to the compatibility table based on: https://github.com/pytorch/vision#installation.
Source code in ultralytics/utils/checks.py
446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 |
|
ultralytics.utils.checks.check_suffix
check_suffix(file='yolo11n.pt', suffix='.pt', msg='')
Check file(s) for acceptable suffix.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
file
|
str | List[str]
|
File or list of files to check. |
'yolo11n.pt'
|
suffix
|
str | tuple
|
Acceptable suffix or tuple of suffixes. |
'.pt'
|
msg
|
str
|
Additional message to display in case of error. |
''
|
Source code in ultralytics/utils/checks.py
480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 |
|
ultralytics.utils.checks.check_yolov5u_filename
check_yolov5u_filename(file: str, verbose: bool = True)
Replace legacy YOLOv5 filenames with updated YOLOv5u filenames.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
file
|
str
|
Filename to check and potentially update. |
required |
verbose
|
bool
|
Whether to print information about the replacement. |
True
|
Returns:
Type | Description |
---|---|
str
|
Updated filename. |
Source code in ultralytics/utils/checks.py
497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 |
|
ultralytics.utils.checks.check_model_file_from_stem
check_model_file_from_stem(model='yolo11n')
Return a model filename from a valid model stem.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
model
|
str
|
Model stem to check. |
'yolo11n'
|
Returns:
Type | Description |
---|---|
str | Path
|
Model filename with appropriate suffix. |
Source code in ultralytics/utils/checks.py
525 526 527 528 529 530 531 532 533 534 535 536 537 538 |
|
ultralytics.utils.checks.check_file
check_file(file, suffix='', download=True, download_dir='.', hard=True)
Search/download file (if necessary), check suffix (if provided), and return path.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
file
|
str
|
File name or path. |
required |
suffix
|
str | tuple
|
Acceptable suffix or tuple of suffixes to validate against the file. |
''
|
download
|
bool
|
Whether to download the file if it doesn't exist locally. |
True
|
download_dir
|
str
|
Directory to download the file to. |
'.'
|
hard
|
bool
|
Whether to raise an error if the file is not found. |
True
|
Returns:
Type | Description |
---|---|
str
|
Path to the file. |
Source code in ultralytics/utils/checks.py
541 542 543 544 545 546 547 548 549 550 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 |
|
ultralytics.utils.checks.check_yaml
check_yaml(file, suffix=('.yaml', '.yml'), hard=True)
Search/download YAML file (if necessary) and return path, checking suffix.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
file
|
str | Path
|
File name or path. |
required |
suffix
|
tuple
|
Tuple of acceptable YAML file suffixes. |
('.yaml', '.yml')
|
hard
|
bool
|
Whether to raise an error if the file is not found or multiple files are found. |
True
|
Returns:
Type | Description |
---|---|
str
|
Path to the YAML file. |
Source code in ultralytics/utils/checks.py
581 582 583 584 585 586 587 588 589 590 591 592 593 |
|
ultralytics.utils.checks.check_is_path_safe
check_is_path_safe(basedir, path)
Check if the resolved path is under the intended directory to prevent path traversal.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
basedir
|
Path | str
|
The intended directory. |
required |
path
|
Path | str
|
The path to check. |
required |
Returns:
Type | Description |
---|---|
bool
|
True if the path is safe, False otherwise. |
Source code in ultralytics/utils/checks.py
596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 |
|
ultralytics.utils.checks.check_imshow
cached
check_imshow(warn=False)
Check if environment supports image displays.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
warn
|
bool
|
Whether to warn if environment doesn't support image displays. |
False
|
Returns:
Type | Description |
---|---|
bool
|
True if environment supports image displays, False otherwise. |
Source code in ultralytics/utils/checks.py
613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 |
|
ultralytics.utils.checks.check_yolo
check_yolo(verbose=True, device='')
Return a human-readable YOLO software and hardware summary.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
verbose
|
bool
|
Whether to print verbose information. |
True
|
device
|
str | device
|
Device to use for YOLO. |
''
|
Source code in ultralytics/utils/checks.py
639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 |
|
ultralytics.utils.checks.collect_system_info
collect_system_info()
Collect and print relevant system information including OS, Python, RAM, CPU, and CUDA.
Returns:
Type | Description |
---|---|
dict
|
Dictionary containing system information. |
Source code in ultralytics/utils/checks.py
673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 |
|
ultralytics.utils.checks.check_amp
check_amp(model)
Check the PyTorch Automatic Mixed Precision (AMP) functionality of a YOLO model.
If the checks fail, it means there are anomalies with AMP on the system that may cause NaN losses or zero-mAP results, so AMP will be disabled during training.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
model
|
Module
|
A YOLO model instance. |
required |
Returns:
Type | Description |
---|---|
bool
|
Returns True if the AMP functionality works correctly with YOLO11 model, else False. |
Examples:
>>> from ultralytics import YOLO
>>> from ultralytics.utils.checks import check_amp
>>> model = YOLO("yolo11n.pt").model.cuda()
>>> check_amp(model)
Source code in ultralytics/utils/checks.py
734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 |
|
ultralytics.utils.checks.print_args
print_args(args: dict | None = None, show_file=True, show_func=False)
Print function arguments (optional args dict).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
args
|
dict
|
Arguments to print. |
None
|
show_file
|
bool
|
Whether to show the file name. |
True
|
show_func
|
bool
|
Whether to show the function name. |
False
|
Source code in ultralytics/utils/checks.py
807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 |
|
ultralytics.utils.checks.cuda_device_count
cuda_device_count() -> int
Get the number of NVIDIA GPUs available in the environment.
Returns:
Type | Description |
---|---|
int
|
The number of NVIDIA GPUs available. |
Source code in ultralytics/utils/checks.py
834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 |
|
ultralytics.utils.checks.cuda_is_available
cuda_is_available() -> bool
Check if CUDA is available in the environment.
Returns:
Type | Description |
---|---|
bool
|
True if one or more NVIDIA GPUs are available, False otherwise. |
Source code in ultralytics/utils/checks.py
860 861 862 863 864 865 866 867 |
|
ultralytics.utils.checks.is_rockchip
is_rockchip()
Check if the current environment is running on a Rockchip SoC.
Returns:
Type | Description |
---|---|
bool
|
True if running on a Rockchip SoC, False otherwise. |
Source code in ultralytics/utils/checks.py
870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 |
|
ultralytics.utils.checks.is_intel
is_intel()
Check if the system has Intel hardware (CPU or GPU).
Returns:
Type | Description |
---|---|
bool
|
True if Intel hardware is detected, False otherwise. |
Source code in ultralytics/utils/checks.py
890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 |
|
ultralytics.utils.checks.is_sudo_available
is_sudo_available() -> bool
Check if the sudo command is available in the environment.
Returns:
Type | Description |
---|---|
bool
|
True if the sudo command is available, False otherwise. |
Source code in ultralytics/utils/checks.py
911 912 913 914 915 916 917 918 919 920 921 |
|