disk_usage返回的三个字段怎么读：total、used与free的单位与含义

如果你在练习脚本里调用 shutil.disk_usage，拿到的是一个命名元组，里面有三个属性：total、used、free。

按 Python 官方 shutil 文档的说明，这三个属性分别表示总空间、已用空间和空闲空间的数量。它们回答的是三个不同问题：total 问“这块文件系统一共有多大”，used 问“其中已经被占用了多少”，free 问“还剩多少可用”。

三个字段是并列关系，不是层层相减的推导关系。文档没有写 used 加 free 一定等于 total，所以读的时候不要把三者当成一道可以互相验算的算术题。你只需要分别记住每个字段对应哪一问。

一个自建情境（示例，不是对某台机器的实测记录）：你在练习目录 exercise/ 下写一个脚本，调用 disk_usage 后把三个属性分别打印出来，观察它们各自是什么数。下面所有路径都是练习用的自建示例。

这三个字段的单位，文档写得很明确：以字节为单位。

total、used、free 三个都是字节数，没有一个是百分比，也没有一个是“GB”或“MB”。所以拿到数字后，如果你习惯按 GB 理解，需要自己换算，而不是把返回值直接当成 GB。

换算本身是普通除法，但要注意两件事。第一，换算是你自己做的，disk_usage 不提供换算后的值。第二，换算用的除数取决于你按哪种口径理解“GB”，文档没有规定用哪一种，所以本文不替你定一个除数，也不给出任何具体数值示例。

一个自建示例（练习数据，不是真实磁盘数据）：

import shutil

usage = shutil.disk_usage("exercise")
print(usage.total)
print(usage.used)
print(usage.free)

这段代码只读取统计信息并打印，不创建、不删除、不修改任何文件。运行前请确认 exercise/ 是你自己建的练习目录。

disk_usage 返回的是命名元组（named tuple），这意味着三个字段既可以用属性名取，也可以按位置下标取。

用属性名取，可读性更好：usage.total、usage.used、usage.free，一眼能看出取的是哪一项。

按下标取，顺序是 total、used、free 依次对应 0、1、2。文档列出的属性顺序就是这个顺序，所以 usage[0] 是 total，usage[1] 是 used，usage[2] 是 free。

两种写法取到的是同一个值，选哪种看你的代码里哪个更清楚。初学阶段建议用属性名，避免记错下标。

一个自建示例（练习数据）：

import shutil

usage = shutil.disk_usage("exercise")
print(usage.total == usage[0])
print(usage.used == usage[1])
print(usage.free == usage[2])

这段代码只做比较和打印，不写文件。三个比较结果应当都是 True，用来确认属性名和下标指向同一项。

传给 disk_usage 的 path，文档说明可以是文件，也可以是目录。

这一点容易误解成“传文件就统计这个文件占多少空间”。不是。三个字段描述的是这块文件系统整体的总空间、已用空间和空闲空间，path 只是用来定位“查哪一块文件系统”。所以传一个文件和一个目录，只要它们在同一块文件系统上，得到的统计口径是同一块盘。

一个自建情境（示例）：你在 exercise/ 目录下放一个自建文本文件 exercise/note.txt，分别用目录路径和文件路径调用一次，观察两次返回的字段含义是否一致。这里只读取统计信息，不修改文件。

需要说清的是：文档没有说明传文件与传目录在返回值上一定完全相同，也没有给出两者差异的规则。本文只讲 path 允许是文件或目录这一点，不替资料补两者结果关系的结论。

这是读这三个字段时最容易被忽略的一条限制。

文档的备注写明：在 Unix 文件系统上，path 必须指向已挂载文件系统分区内的一个路径。在这些平台上，CPython 不会尝试从非挂载的文件系统获取磁盘使用信息。

这句话的意思是：如果你传的路径不在任何已挂载的分区里，就不要指望拿到有意义的统计。文档没有描述这种情况下具体会返回什么或抛出什么，所以本文不补这部分行为，只把限制本身讲清楚。

判断路径是否落在已挂载分区内，属于系统层面的查看，不在本文操作范围内。本文只提醒：在 Unix 上调用前，先确认你传的练习路径位于一个正常挂载的文件系统里，而不是某种未挂载的特殊位置。

一个边界：这条限制写在 Unix 文件系统上。文档另有一处版本说明，Windows 上 path 可以是文件或目录，但文档没有对 Windows 给出对应的挂载限制表述，本文不替它补。

在动手写脚本之前，先确认两件事：平台和版本。

平台方面，文档标注 disk_usage 的可用范围是 Unix 和 Windows。也就是说，这两个平台之外的环境，文档没有承诺这个函数可用。

版本方面，文档写明这个函数在 3.3 版本加入。如果你的 Python 版本早于 3.3，这个函数不存在。文档还有一条版本变更说明：3.8 起，在 Windows 上 path 可以是文件或目录。

所以核对顺序是：先看你的 Python 版本是否不低于 3.3，再看平台是不是 Unix 或 Windows，最后按平台确认 path 的写法。这三项都过了，再谈三个字段怎么读。

本文不给出任何具体版本号之外的性能或行为结论，也不声称在某个环境里运行过。

把前面几节收成一份可以逐条对照的检查清单（以下为编辑整理的核对建议，不是官方规定）：

1. 先确认单位。三个字段都是字节，不要直接当成 GB 或百分比。需要换算时自己除，除数口径由你决定，文档没有规定。

2. 再确认 path 指向哪块文件系统。path 可以是文件或目录，但统计的是所在文件系统的整体情况，不是单个文件的大小。

3. 在 Unix 上确认 path 位于已挂载分区内。这是文档明确写出的限制，不满足时不要依赖返回值。

还有一条边界要记住：本文只讲这三个属性的含义、单位和 path 的挂载限制，不讲容量规划，也不给任何磁盘剩余空间的判断标准。文档没有提供这类标准，本文也不补。