Ultralytics 下载工具模块源码级解析safe_download、attempt_download_asset 与数据集资产自动获取机制【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralyticsUltralytics 的ultralytics/utils/downloads.py是一个几乎贯穿整个项目生命周期的基础工具模块——无论是训练时自动拉取 YOLO 预训练权重、下载 COCO 等数据集压缩包、加载 ReID 模型权重还是为 SAM/相似度检索准备素材都离不开它。本文以 downloads 模块文档 为主体结合该模块源码及其在仓库中的真实调用链数据集 YAML、权重加载、测试用例逐函数剖析 URL 校验、压缩归档、磁盘检查、断点续传、GitHub 资产解析与并发下载的实现细节让你既能直接用这些函数处理自己的资源下载任务也能理解 Ultralytics 内部下载即服务的完整链路。模块概览与公开 APIdocs/en/reference/utils/downloads.md是该模块的 API 参考页由 mkdocstrings 通过::: ultralytics.utils.downloads.xxx指令从源码 docstring 自动生成。因此最权威的事实源就是 ultralytics/utils/downloads.pyAGPL-3.0 协议。模块整体依赖ultralytics.utils提供的ASSETS_URL、LOGGER、TQDM、clean_url、emojis、is_online、url2file等基础设施见 ultralytics/utils/init.py。该模块对外提供 10 个公开函数和一组资产清单常量覆盖下载这一动作的完整生命周期类别函数一句话职责校验类is_url判断字符串是否为合法 URL可选在线探测校验类check_disk_space下载前检查磁盘剩余空间是否充足清理类delete_dsstore递归删除.DS_Store等系统残留文件归档类zip_directory将目录压缩为同名.zip支持排除清单与进度条归档类unzip_file安全解压.zip具备防路径穿越过滤驱动类get_google_drive_file_info把 Google Drive 分享链接转换为直链与文件名驱动类safe_download单文件核心下载引擎重试/断点/校验/解压驱动类get_github_assets查询 GitHub Releases 的 tag 与资产列表驱动类attempt_download_asset按本地→权重目录→URL→Release顺序尝试取权重驱动类download面向 URL 列表的高层入口支持多线程并发模块还定义了两个模块级常量downloads.pyGITHUB_ASSETS_REPO ultralytics/assets预训练权重仓库标识GITHUB_ASSETS_NAMES一个frozenset枚举了从 YOLOv3/v5/v8/v9/v10/v11/v12/v26、YOLOE、SAM、FastSAM、RT-DETR、YOLO-NAS 到 MobileSAM、MobileCLIP 等全部官方权重文件名GITHUB_ASSETS_STEMS是对应的去扩展名集合用于streamlit_inference等场景判断输入的.pt是否为官方资产名。URL 校验与在线探测is_urldef is_url(url: str | Path, check: bool False) - bool:实现要点downloads.py内部使用urllib.parse.urlparse解析只有同时具备scheme如https与netloc域名才判为合法 URL当checkTrue时通过requests.head(url, timeout3, allow_redirectsTrue).ok进一步探测该 URL 是否真实可达——注意这里把requests放在函数内部导入scoped as slow import避免在仅做字符串校验时拖慢导入整个函数用try/except包裹任何解析异常都会安全返回False适合作为路径还是 URL的判据。典型用法是把一个可能来自命令行或 YAML 的字符串先判型。仓库中 ultralytics/nn/autobackend.py 在构造推理后端前就引入了is_url用于区分本地模型路径与远程模型地址。下载前的空间保障check_disk_spacedef check_disk_space( file_bytes: int, path: str | Path | None None, sf: float 1.5, hard: bool True, ) - bool当预期文件较大源码中超过 1 MB时safe_download会先调用本函数做预防性检查。其逻辑downloads.py用shutil.disk_usage(path or Path.cwd())拿到目标分区总容量与剩余空间若文件系统无法汇报用量total 0或file_bytes * sf free直接放行其中sf为安全系数默认 1.5即要求剩余空间 ≥ 预估大小的 1.5 倍空间不足时若hardTrue默认抛出MemoryError否则仅记录LOGGER.warning并返回False报错文案里的字节格式化做了细致的 KB/MB/GB 分级低于 51 KB 显示 KB 档避免出现误导性的0.0 MB。系统残留清理delete_dsstoredef delete_dsstore(path: str | Path, files_to_delete: tuple (.DS_Store, __MACOSX)) - NonemacOS 会在文件夹中生成隐藏的.DS_Store元数据文件与__MACOSX目录跨平台拷贝数据集时常混入压缩包并污染训练目录。本函数downloads.py使用rglob递归收集匹配项并按路径深度降序删除先删深层再删浅层避免删除目录后其父级匹配失效目录用shutil.rmtree普通文件用unlink对符号链接则统一走unlink分支以避免误删链接指向的真实数据。该函数是zip_directory压缩前的默认前置清理步骤。目录打包与安全解压zip_directory / unzip_file打包zip_directorydef zip_directory(directory, compressTrue, exclude(.DS_Store, __MACOSX), progressTrue) - Path实现细节downloads.py先delete_dsstore清理目录再校验目录存在否则抛FileNotFoundError收集目录下所有普通文件并过滤掉排除清单命中项输出zip_file directory.with_suffix(.zip)即与源目录同级的同名 zipcompressTrue时用ZIP_DEFLATED否则用ZIP_STORED仅归档不压缩写入时经TQDM渲染进度条存档路径用file.relative_to(directory)保证 zip 内部结构干净不含外层目录名。仓库中 ultralytics/data/converter.py 引入zip_directory用于数据集格式转换后把 YOLO 标签目录打成 zip 以便分发。解压unzip_file 与 zip-slip 防护def unzip_file(file, pathNone, exclude(.DS_Store, __MACOSX), exist_okFalse, progressTrue) - Path解压逻辑downloads.py值得重点展开入口校验文件必须存在且通过zipfile.is_zipfile检测否则抛BadZipFilepath缺省时使用 zip 所在目录。顶层结构推断统计 zip 内所有成员文件的顶层目录集合。若只有一个顶层目录典型如coco8/整包则直接解压到path如../datasets若顶层散落多个文件则新建以 zip 文件名去扩展名命名的子目录收纳避免污染父目录。幂等保护当目标目录已存在且非空、且exist_okFalse时跳过解压并LOGGER.warning提示直接返回该目录——这就是重复执行下载/解压不会重复拉取的机制来源。路径穿越防护逐成员计算target (extract_path / member).resolve()一旦成员路径为绝对路径、包含..段、或 resolve 后跳出目标目录前缀即判定为不安全并跳过防止恶意 zip 把文件写到解压目录之外。tests/test_python.py中的 test_safe_download_skips_unsafe_archive_members 专门构造了包含../unsafe.txt的恶意 zip 验证该防线断言穿越文件不存在、安全成员被正常解压。Google Drive 直链解析get_google_drive_file_infodef get_google_drive_file_info(link: str) - tuple[str, str | None]Google Drive 的分享链接不能直接用于程序下载本函数负责转换downloads.py从形如https://drive.google.com/file/d/FILE_ID/view?uspdrive_link的链接中切出FILE_ID构造exportdownloadid...的直链用requests.Session流式发起 GET模拟浏览器首次访问若响应内容命中quota exceeded抛出带表情符号提示的ConnectionError告知下载配额耗尽请稍后重试或手动下载若 Cookie 中出现download_warning说明文件较大需要确认令牌会把该 token 以confirmtoken拼回直链从响应头content-disposition中用正则提取原始文件名提取失败则返回None。核心下载引擎safe_downloadsafe_download是整个模块的中枢它把URL 判定、直链转换、重试、部分下载检测、磁盘预检、解压、清理串成一条流水线。def safe_download( url, fileNone, dirNone, unzipTrue, deleteFalse, curlFalse, retry3, min_bytes1e0, exist_okFalse, progressTrue, ) - Path | str各参数含义如下参数默认值说明url必填待下载地址若指向本地已存在文件且不含://则直接走本地分支fileNone保存文件名缺省时由url2file从 URL 尾部推断dirNone保存目录缺省为当前工作目录父目录会自动mkdir(parentsTrue)unzipTrue下载后若为 zip/tar/gz 则自动解压deleteFalse解压完成后删除归档文件curlFalse优先调用系统curl而非requestsretry3失败重试次数上限min_bytes1e0判定下载成功的最小字节数防止拿到空/极小残片exist_okFalse透传给unzip_file控制已存在目录的处理progressTrue是否显示 TQDM 进度条下载过程的高可信设计实现downloads.py中包含几处值得称道的健壮性设计临时文件 原子发布先写到名为.target.uuid4.part的临时文件只有通过大小校验后才f.replace(target)发布到正式文件名避免留下半截文件被误当完整缓存命中的问题双引擎切换curl参数为真或第 1 次重试后若系统装有 curlshutil.which(curl)探测就改用 curl 下载并附加--connect-timeout 30 --speed-limit 1 --speed-time 300的停摆检测连接超时 30s、低于 1 B/s 持续 300s 即判定死连接防止坏连接阻塞解释器退出curl 还支持-C -断点续传重试时可续传.part残片Content-Length 部分下载检测requests分支会读取Content-Length作为expected_size下载结束后比对文件实际大小不一致时输出Partial download: x/y bytes (百分比)警告从而发现被服务端截断的下载磁盘预检首次尝试且expected_size 10485761 MB时先check_disk_spaceMemoryError会被立刻原样抛出、不做无意义重试离线环境快速失败首次失败时若is_online()基于 DNS 解析探测见 ultralytics/utils/init.py返回False直接删除残片并抛ConnectionError避免在离线环境里空转 3 次重试重试耗尽兜底重试结束仍未成功则清理.part文件并抛出包含Retry limit reached的ConnectionError下载地址会先clean_url去除认证参数、把ASSETS_URL前缀规范化为官方资产站再用emojis包装人类可读的日志。下载后的自动解压与 tar 安全当unzipTrue且后缀为/.zip/.tar/.gz时zip 走unzip_file解压到dir或原地.tar/.gz走tarfile.open(f, r:*)逐成员手工提取且只接受普通文件与目录——跳过符号链接、硬链接等成员并做与 zip 相同的绝对路径 /../ 越界三重校验配合tests/test_python.py的 test_safe_download_skips_unsafe_tar_members 可验证其防穿越能力deleteTrue时解压完删除归档。tests/test_python.py的 test_safe_download_unzips_local_path_archive 则验证了本地 zip 路径也能直接喂给safe_download这一分支构造好本地coco8 local.zip后调用safe_download(archive, dir..., unzipTrue)断言解压出的目录结构与data.yaml完整落盘。GitHub Releases 资产解析与权重自动下载常量清单GITHUB_ASSETS_NAMES模块顶部用列表推导式一次性生成了所有官方权重名downloads.py例如yolo26{n/s/m/l/x}.pt及-cls/-seg/-sem/-pose/-obb/-depth变体、yolo26*-objv1{-150,-seg}系列yolo11/yolo12/yolov8系列detect/classify/segment/pose/obb 等后缀YOLOv3/v5/v9/v10、YOLO-World、YOLOE、SAM/SAM2、FastSAM、RT-DETR、MobileSAM、MobileCLIP 等历史资产。这份白名单决定了attempt_download_asset能否走已知官方资产快路径。get_github_assets查询 Release 元数据def get_github_assets(repoultralytics/assets, versionlatest, retryFalse) - tuple[str, list[str]]该函数downloads.py调用 GitHub Releases API 获取指定仓库、指定版本version ! latest时自动拼接为tags/version的发布 tag 与资产文件名列表。对 403 速率限制不做重试会浪费配额且无用对瞬时网络异常在retryTrue时只多试一次失败则返回(, [])空值交由调用方走 latest 兜底。attempt_download_asset按优先级取权重def attempt_download_asset(file, repoultralytics/assets, releasev8.4.0, **kwargs) - str这是训练/推理时给一个权重名就自动拿到本地路径的入口查找顺序清晰可循downloads.py先经checks.check_yolov5u_filename兼容处理 YOLOv3/v5 的-u命名升级再剔除引号与空白文件在当前目录存在 → 直接返回否则查用户配置的SETTINGS[weights_dir]权重缓存目录该设置来自 ultralytics/utils/settings 初始化的SettingsManager都未命中则分三类处理传入的是完整 URL解码并解析出文件名后调safe_downloadmin_bytes1e5传入名命中GITHUB_ASSETS_NAMES白名单按repo/release构造官方资产直链快速下载其它仓库/版本先get_github_assets查询空结果再回退到该仓库 latest release确认资产存在后下载。它被广泛用在模型加载路径上。例如 ultralytics/nn/tasks.py 的torch_safe_load加载任意.pt前都会执行file attempt_download_asset(weight)实现只给yolo26n.pt也能联网自取同样依赖它的还有 SAM 构建、NAS 模型、文本模型、ReID 特征提取跟踪时按需拉取外观重识别权重以及 TensorFlow 导出后端data/scripts/download_weights.sh 也会批量调用它来缓存全套权重。并发下载入口downloaddef download( url: str | list[str] | Path, dirNone, unzipTrue, deleteFalse, curlFalse, threads1, retry3, exist_okFalse, ) - Nonedownload是面向数据集/批量文件的顶层 APIdownloads.py在ultralytics/__init__.py中被 re-export因此可直接from ultralytics import download自动创建目标目录mkdir(parentsTrue, exist_okTrue)支持单个 URL、Path 或 URL 列表threads 1时用multiprocessing.pool.ThreadPool把每个 URL 与相同目标目录zip配对并发调用safe_download注意线程数即并发下载数单线程时逐 URL 顺序执行。数据集 YAML 中的真实用法YOLO 数据集的自动下载脚本正是以 YAML 里的download:代码块为载体的例如 coco.yaml 的下载脚本download: | from pathlib import Path from ultralytics.utils import ASSETS_URL from ultralytics.utils.downloads import download segments True # segment or box labels dir Path(yaml[path]) # dataset root dir urls [ASSETS_URL (/coco2017labels-segments.zip if segments else /coco2017labels.zip)] download(urls, dirdir.parent) urls [ http://images.cocodataset.org/zips/train2017.zip, # 19G, 118k images http://images.cocodataset.org/zips/val2017.zip, # 1G, 5k images ] download(urls, dirdir / images, threads3)COCO 这种大体积数据集就通过threads3并行拉取多路镜像数据。而check_datasetultralytics/data/utils.py在真正校验数据前会先用zipfile.is_zipfile/is_tarfile判断用户给的是否为归档包是则调safe_download(..., dirDATASETS_DIR, unzipTrue)解压到全局数据集目录再继续读取内部 YAML、把缺失的train/val/names/nc逐项校验补齐——safe_download因此成为拿到任意格式数据集就能一键就绪的基础设施。相似的自动下载逻辑还分布在 Argoverse.yaml、VisDrone.yaml、SKU-110K.yaml 等几十个内置数据集 YAML 中。端到端实践示例把模块各函数串起来可以覆盖日常几乎全部资源获取场景from pathlib import Path from ultralytics.utils.downloads import ( download, safe_download, attempt_download_asset, unzip_file, zip_directory, is_url ) # 1) 校验并下载单文件自动解压后删除归档 if is_url(https://example.com/assets/demo.zip): path safe_download(https://example.com/assets/demo.zip, dirdownloads, unzipTrue, deleteTrue, retry5) # 2) 自动获取 YOLO26 官方权重白名单/URL/Release 多级兜底 local_ckpt attempt_download_asset(yolo26n.pt) # 3) 并行下载一组素材线程数 并发连接数 download([https://example.com/a.zip, https://example.com/b.zip], dirdownloads, threads2) # 4) 本地目录打包 / 解压含系统残留清理与防穿越校验 zip_file zip_directory(Path(my_labels), progressTrue) out_dir unzip_file(zip_file, pathdownloads, exist_okFalse)总结ultralytics/utils/downloads.py虽然是一组底层工具函数却在多个层面定义了 Ultralytics 资源管理的可靠性基线临时文件原子发布与 Content-Length 比对杜绝了残缺文件混入curl 断点续传与重试分级应对网络抖动磁盘预检与is_online探测避免无效重试zip/tar 双重防路径穿越保障解压安全GITHUB_ASSETS_NAMES白名单 Release 动态查询则让输入模型名即得权重文件成为可能。理解了这条下载链无论你是想复用自己的数据集 YAML、写脚本批量预热权重缓存还是在离线内网环境排查卡在下载/重试的报错都能快速定位到对应环节并给出正确的参数组合。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ultralytics 下载工具模块源码级解析：safe_download、attempt_download_asset 与数据集资产自动获取机制
Ultralytics 下载工具模块源码级解析safe_download、attempt_download_asset 与数据集资产自动获取机制【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralyticsUltralytics 的ultralytics/utils/downloads.py是一个几乎贯穿整个项目生命周期的基础工具模块——无论是训练时自动拉取 YOLO 预训练权重、下载 COCO 等数据集压缩包、加载 ReID 模型权重还是为 SAM/相似度检索准备素材都离不开它。本文以 downloads 模块文档 为主体结合该模块源码及其在仓库中的真实调用链数据集 YAML、权重加载、测试用例逐函数剖析 URL 校验、压缩归档、磁盘检查、断点续传、GitHub 资产解析与并发下载的实现细节让你既能直接用这些函数处理自己的资源下载任务也能理解 Ultralytics 内部下载即服务的完整链路。模块概览与公开 APIdocs/en/reference/utils/downloads.md是该模块的 API 参考页由 mkdocstrings 通过::: ultralytics.utils.downloads.xxx指令从源码 docstring 自动生成。因此最权威的事实源就是 ultralytics/utils/downloads.pyAGPL-3.0 协议。模块整体依赖ultralytics.utils提供的ASSETS_URL、LOGGER、TQDM、clean_url、emojis、is_online、url2file等基础设施见 ultralytics/utils/init.py。该模块对外提供 10 个公开函数和一组资产清单常量覆盖下载这一动作的完整生命周期类别函数一句话职责校验类is_url判断字符串是否为合法 URL可选在线探测校验类check_disk_space下载前检查磁盘剩余空间是否充足清理类delete_dsstore递归删除.DS_Store等系统残留文件归档类zip_directory将目录压缩为同名.zip支持排除清单与进度条归档类unzip_file安全解压.zip具备防路径穿越过滤驱动类get_google_drive_file_info把 Google Drive 分享链接转换为直链与文件名驱动类safe_download单文件核心下载引擎重试/断点/校验/解压驱动类get_github_assets查询 GitHub Releases 的 tag 与资产列表驱动类attempt_download_asset按本地→权重目录→URL→Release顺序尝试取权重驱动类download面向 URL 列表的高层入口支持多线程并发模块还定义了两个模块级常量downloads.pyGITHUB_ASSETS_REPO ultralytics/assets预训练权重仓库标识GITHUB_ASSETS_NAMES一个frozenset枚举了从 YOLOv3/v5/v8/v9/v10/v11/v12/v26、YOLOE、SAM、FastSAM、RT-DETR、YOLO-NAS 到 MobileSAM、MobileCLIP 等全部官方权重文件名GITHUB_ASSETS_STEMS是对应的去扩展名集合用于streamlit_inference等场景判断输入的.pt是否为官方资产名。URL 校验与在线探测is_urldef is_url(url: str | Path, check: bool False) - bool:实现要点downloads.py内部使用urllib.parse.urlparse解析只有同时具备scheme如https与netloc域名才判为合法 URL当checkTrue时通过requests.head(url, timeout3, allow_redirectsTrue).ok进一步探测该 URL 是否真实可达——注意这里把requests放在函数内部导入scoped as slow import避免在仅做字符串校验时拖慢导入整个函数用try/except包裹任何解析异常都会安全返回False适合作为路径还是 URL的判据。典型用法是把一个可能来自命令行或 YAML 的字符串先判型。仓库中 ultralytics/nn/autobackend.py 在构造推理后端前就引入了is_url用于区分本地模型路径与远程模型地址。下载前的空间保障check_disk_spacedef check_disk_space( file_bytes: int, path: str | Path | None None, sf: float 1.5, hard: bool True, ) - bool当预期文件较大源码中超过 1 MB时safe_download会先调用本函数做预防性检查。其逻辑downloads.py用shutil.disk_usage(path or Path.cwd())拿到目标分区总容量与剩余空间若文件系统无法汇报用量total 0或file_bytes * sf free直接放行其中sf为安全系数默认 1.5即要求剩余空间 ≥ 预估大小的 1.5 倍空间不足时若hardTrue默认抛出MemoryError否则仅记录LOGGER.warning并返回False报错文案里的字节格式化做了细致的 KB/MB/GB 分级低于 51 KB 显示 KB 档避免出现误导性的0.0 MB。系统残留清理delete_dsstoredef delete_dsstore(path: str | Path, files_to_delete: tuple (.DS_Store, __MACOSX)) - NonemacOS 会在文件夹中生成隐藏的.DS_Store元数据文件与__MACOSX目录跨平台拷贝数据集时常混入压缩包并污染训练目录。本函数downloads.py使用rglob递归收集匹配项并按路径深度降序删除先删深层再删浅层避免删除目录后其父级匹配失效目录用shutil.rmtree普通文件用unlink对符号链接则统一走unlink分支以避免误删链接指向的真实数据。该函数是zip_directory压缩前的默认前置清理步骤。目录打包与安全解压zip_directory / unzip_file打包zip_directorydef zip_directory(directory, compressTrue, exclude(.DS_Store, __MACOSX), progressTrue) - Path实现细节downloads.py先delete_dsstore清理目录再校验目录存在否则抛FileNotFoundError收集目录下所有普通文件并过滤掉排除清单命中项输出zip_file directory.with_suffix(.zip)即与源目录同级的同名 zipcompressTrue时用ZIP_DEFLATED否则用ZIP_STORED仅归档不压缩写入时经TQDM渲染进度条存档路径用file.relative_to(directory)保证 zip 内部结构干净不含外层目录名。仓库中 ultralytics/data/converter.py 引入zip_directory用于数据集格式转换后把 YOLO 标签目录打成 zip 以便分发。解压unzip_file 与 zip-slip 防护def unzip_file(file, pathNone, exclude(.DS_Store, __MACOSX), exist_okFalse, progressTrue) - Path解压逻辑downloads.py值得重点展开入口校验文件必须存在且通过zipfile.is_zipfile检测否则抛BadZipFilepath缺省时使用 zip 所在目录。顶层结构推断统计 zip 内所有成员文件的顶层目录集合。若只有一个顶层目录典型如coco8/整包则直接解压到path如../datasets若顶层散落多个文件则新建以 zip 文件名去扩展名命名的子目录收纳避免污染父目录。幂等保护当目标目录已存在且非空、且exist_okFalse时跳过解压并LOGGER.warning提示直接返回该目录——这就是重复执行下载/解压不会重复拉取的机制来源。路径穿越防护逐成员计算target (extract_path / member).resolve()一旦成员路径为绝对路径、包含..段、或 resolve 后跳出目标目录前缀即判定为不安全并跳过防止恶意 zip 把文件写到解压目录之外。tests/test_python.py中的 test_safe_download_skips_unsafe_archive_members 专门构造了包含../unsafe.txt的恶意 zip 验证该防线断言穿越文件不存在、安全成员被正常解压。Google Drive 直链解析get_google_drive_file_infodef get_google_drive_file_info(link: str) - tuple[str, str | None]Google Drive 的分享链接不能直接用于程序下载本函数负责转换downloads.py从形如https://drive.google.com/file/d/FILE_ID/view?uspdrive_link的链接中切出FILE_ID构造exportdownloadid...的直链用requests.Session流式发起 GET模拟浏览器首次访问若响应内容命中quota exceeded抛出带表情符号提示的ConnectionError告知下载配额耗尽请稍后重试或手动下载若 Cookie 中出现download_warning说明文件较大需要确认令牌会把该 token 以confirmtoken拼回直链从响应头content-disposition中用正则提取原始文件名提取失败则返回None。核心下载引擎safe_downloadsafe_download是整个模块的中枢它把URL 判定、直链转换、重试、部分下载检测、磁盘预检、解压、清理串成一条流水线。def safe_download( url, fileNone, dirNone, unzipTrue, deleteFalse, curlFalse, retry3, min_bytes1e0, exist_okFalse, progressTrue, ) - Path | str各参数含义如下参数默认值说明url必填待下载地址若指向本地已存在文件且不含://则直接走本地分支fileNone保存文件名缺省时由url2file从 URL 尾部推断dirNone保存目录缺省为当前工作目录父目录会自动mkdir(parentsTrue)unzipTrue下载后若为 zip/tar/gz 则自动解压deleteFalse解压完成后删除归档文件curlFalse优先调用系统curl而非requestsretry3失败重试次数上限min_bytes1e0判定下载成功的最小字节数防止拿到空/极小残片exist_okFalse透传给unzip_file控制已存在目录的处理progressTrue是否显示 TQDM 进度条下载过程的高可信设计实现downloads.py中包含几处值得称道的健壮性设计临时文件 原子发布先写到名为.target.uuid4.part的临时文件只有通过大小校验后才f.replace(target)发布到正式文件名避免留下半截文件被误当完整缓存命中的问题双引擎切换curl参数为真或第 1 次重试后若系统装有 curlshutil.which(curl)探测就改用 curl 下载并附加--connect-timeout 30 --speed-limit 1 --speed-time 300的停摆检测连接超时 30s、低于 1 B/s 持续 300s 即判定死连接防止坏连接阻塞解释器退出curl 还支持-C -断点续传重试时可续传.part残片Content-Length 部分下载检测requests分支会读取Content-Length作为expected_size下载结束后比对文件实际大小不一致时输出Partial download: x/y bytes (百分比)警告从而发现被服务端截断的下载磁盘预检首次尝试且expected_size 10485761 MB时先check_disk_spaceMemoryError会被立刻原样抛出、不做无意义重试离线环境快速失败首次失败时若is_online()基于 DNS 解析探测见 ultralytics/utils/init.py返回False直接删除残片并抛ConnectionError避免在离线环境里空转 3 次重试重试耗尽兜底重试结束仍未成功则清理.part文件并抛出包含Retry limit reached的ConnectionError下载地址会先clean_url去除认证参数、把ASSETS_URL前缀规范化为官方资产站再用emojis包装人类可读的日志。下载后的自动解压与 tar 安全当unzipTrue且后缀为/.zip/.tar/.gz时zip 走unzip_file解压到dir或原地.tar/.gz走tarfile.open(f, r:*)逐成员手工提取且只接受普通文件与目录——跳过符号链接、硬链接等成员并做与 zip 相同的绝对路径 /../ 越界三重校验配合tests/test_python.py的 test_safe_download_skips_unsafe_tar_members 可验证其防穿越能力deleteTrue时解压完删除归档。tests/test_python.py的 test_safe_download_unzips_local_path_archive 则验证了本地 zip 路径也能直接喂给safe_download这一分支构造好本地coco8 local.zip后调用safe_download(archive, dir..., unzipTrue)断言解压出的目录结构与data.yaml完整落盘。GitHub Releases 资产解析与权重自动下载常量清单GITHUB_ASSETS_NAMES模块顶部用列表推导式一次性生成了所有官方权重名downloads.py例如yolo26{n/s/m/l/x}.pt及-cls/-seg/-sem/-pose/-obb/-depth变体、yolo26*-objv1{-150,-seg}系列yolo11/yolo12/yolov8系列detect/classify/segment/pose/obb 等后缀YOLOv3/v5/v9/v10、YOLO-World、YOLOE、SAM/SAM2、FastSAM、RT-DETR、MobileSAM、MobileCLIP 等历史资产。这份白名单决定了attempt_download_asset能否走已知官方资产快路径。get_github_assets查询 Release 元数据def get_github_assets(repoultralytics/assets, versionlatest, retryFalse) - tuple[str, list[str]]该函数downloads.py调用 GitHub Releases API 获取指定仓库、指定版本version ! latest时自动拼接为tags/version的发布 tag 与资产文件名列表。对 403 速率限制不做重试会浪费配额且无用对瞬时网络异常在retryTrue时只多试一次失败则返回(, [])空值交由调用方走 latest 兜底。attempt_download_asset按优先级取权重def attempt_download_asset(file, repoultralytics/assets, releasev8.4.0, **kwargs) - str这是训练/推理时给一个权重名就自动拿到本地路径的入口查找顺序清晰可循downloads.py先经checks.check_yolov5u_filename兼容处理 YOLOv3/v5 的-u命名升级再剔除引号与空白文件在当前目录存在 → 直接返回否则查用户配置的SETTINGS[weights_dir]权重缓存目录该设置来自 ultralytics/utils/settings 初始化的SettingsManager都未命中则分三类处理传入的是完整 URL解码并解析出文件名后调safe_downloadmin_bytes1e5传入名命中GITHUB_ASSETS_NAMES白名单按repo/release构造官方资产直链快速下载其它仓库/版本先get_github_assets查询空结果再回退到该仓库 latest release确认资产存在后下载。它被广泛用在模型加载路径上。例如 ultralytics/nn/tasks.py 的torch_safe_load加载任意.pt前都会执行file attempt_download_asset(weight)实现只给yolo26n.pt也能联网自取同样依赖它的还有 SAM 构建、NAS 模型、文本模型、ReID 特征提取跟踪时按需拉取外观重识别权重以及 TensorFlow 导出后端data/scripts/download_weights.sh 也会批量调用它来缓存全套权重。并发下载入口downloaddef download( url: str | list[str] | Path, dirNone, unzipTrue, deleteFalse, curlFalse, threads1, retry3, exist_okFalse, ) - Nonedownload是面向数据集/批量文件的顶层 APIdownloads.py在ultralytics/__init__.py中被 re-export因此可直接from ultralytics import download自动创建目标目录mkdir(parentsTrue, exist_okTrue)支持单个 URL、Path 或 URL 列表threads 1时用multiprocessing.pool.ThreadPool把每个 URL 与相同目标目录zip配对并发调用safe_download注意线程数即并发下载数单线程时逐 URL 顺序执行。数据集 YAML 中的真实用法YOLO 数据集的自动下载脚本正是以 YAML 里的download:代码块为载体的例如 coco.yaml 的下载脚本download: | from pathlib import Path from ultralytics.utils import ASSETS_URL from ultralytics.utils.downloads import download segments True # segment or box labels dir Path(yaml[path]) # dataset root dir urls [ASSETS_URL (/coco2017labels-segments.zip if segments else /coco2017labels.zip)] download(urls, dirdir.parent) urls [ http://images.cocodataset.org/zips/train2017.zip, # 19G, 118k images http://images.cocodataset.org/zips/val2017.zip, # 1G, 5k images ] download(urls, dirdir / images, threads3)COCO 这种大体积数据集就通过threads3并行拉取多路镜像数据。而check_datasetultralytics/data/utils.py在真正校验数据前会先用zipfile.is_zipfile/is_tarfile判断用户给的是否为归档包是则调safe_download(..., dirDATASETS_DIR, unzipTrue)解压到全局数据集目录再继续读取内部 YAML、把缺失的train/val/names/nc逐项校验补齐——safe_download因此成为拿到任意格式数据集就能一键就绪的基础设施。相似的自动下载逻辑还分布在 Argoverse.yaml、VisDrone.yaml、SKU-110K.yaml 等几十个内置数据集 YAML 中。端到端实践示例把模块各函数串起来可以覆盖日常几乎全部资源获取场景from pathlib import Path from ultralytics.utils.downloads import ( download, safe_download, attempt_download_asset, unzip_file, zip_directory, is_url ) # 1) 校验并下载单文件自动解压后删除归档 if is_url(https://example.com/assets/demo.zip): path safe_download(https://example.com/assets/demo.zip, dirdownloads, unzipTrue, deleteTrue, retry5) # 2) 自动获取 YOLO26 官方权重白名单/URL/Release 多级兜底 local_ckpt attempt_download_asset(yolo26n.pt) # 3) 并行下载一组素材线程数 并发连接数 download([https://example.com/a.zip, https://example.com/b.zip], dirdownloads, threads2) # 4) 本地目录打包 / 解压含系统残留清理与防穿越校验 zip_file zip_directory(Path(my_labels), progressTrue) out_dir unzip_file(zip_file, pathdownloads, exist_okFalse)总结ultralytics/utils/downloads.py虽然是一组底层工具函数却在多个层面定义了 Ultralytics 资源管理的可靠性基线临时文件原子发布与 Content-Length 比对杜绝了残缺文件混入curl 断点续传与重试分级应对网络抖动磁盘预检与is_online探测避免无效重试zip/tar 双重防路径穿越保障解压安全GITHUB_ASSETS_NAMES白名单 Release 动态查询则让输入模型名即得权重文件成为可能。理解了这条下载链无论你是想复用自己的数据集 YAML、写脚本批量预热权重缓存还是在离线内网环境排查卡在下载/重试的报错都能快速定位到对应环节并给出正确的参数组合。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考