Checking Physical Disk Space Layouts

Understanding how much disk space is available on a system is a fundamental task for any engineer working with servers or applications. Before you can move files, create backups, or deploy new software, you need to know how much room you have to work with. Python provides a simple and reliable way to check disk space using the shutil module, which gives you detailed information about the physical storage layout of your system.

⚙️ Why Check Disk Space?

• Prevent failures – Running out of disk space can crash applications or prevent log files from being written.
• Plan capacity – Knowing current usage helps you decide when to add more storage or clean up old files.
• Automate monitoring – You can write scripts that alert you when disk usage crosses a threshold.
• Verify mounts – Ensure external drives, network shares, or cloud volumes are properly attached and accessible.

📊 The Key Function: shutil.disk_usage()

The shutil module includes a function called disk_usage() that takes a path as input and returns a named tuple with three important values:

• total – The total disk space on the drive or partition, in bytes.
• used – The amount of space currently in use, in bytes.
• free – The amount of space still available, in bytes.

You call it by passing a path string to the function, like shutil.disk_usage("/") for the root drive on Linux or shutil.disk_usage("C:\") on Windows.

🛠️ How to Use It in a Script

Here is a simple example of how you might check disk space in a Python script:

• First, import the shutil module.
• Then, call shutil.disk_usage() with the path you want to inspect.
• Store the result in a variable, such as usage.
• Access the values using usage.total, usage.used, and usage.free.

To make the output human-readable, you can convert bytes to gigabytes by dividing by 1024 three times (bytes to kilobytes, kilobytes to megabytes, megabytes to gigabytes). A common approach is to define a helper function that does this conversion automatically.

📋 Comparison: Bytes vs. Human-Readable Format

Engineers almost always work with human-readable formats because raw byte values are too large to interpret quickly.

🕵️ Checking Multiple Drives or Mount Points

In many environments, you will have multiple drives or partitions. You can check each one by calling disk_usage() with different paths:

• For the root drive: shutil.disk_usage("/")
• For a data drive mounted at /data: shutil.disk_usage("/data")
• For a backup drive at /mnt/backup: shutil.disk_usage("/mnt/backup")

You can loop through a list of paths and print the disk usage for each one, making it easy to monitor an entire server with a single script.

⚠️ Important Notes for Engineers

• Path must exist – If the path you pass to disk_usage() does not exist, Python will raise a FileNotFoundError. Always verify the path first.
• Permissions matter – On some systems, you may need elevated privileges to query certain drives or partitions.
• Cross-platform – The shutil.disk_usage() function works on Windows, macOS, and Linux, making it a reliable choice for scripts that run on multiple operating systems.
• Real-time values – The values returned are a snapshot at the moment the function is called. Disk usage can change rapidly on busy systems.

🧪 Practical Use Case: Alerting on Low Disk Space

A common pattern is to check disk space and send an alert if free space drops below a certain threshold. For example:

• Define a threshold, such as 10 GB.
• Call shutil.disk_usage() for the root drive.
• Compare usage.free to your threshold.
• If free space is below the threshold, print a warning or log the event.

This kind of check can be scheduled to run every hour using a cron job or task scheduler, giving you early warning before disk space becomes a critical issue.

✅ Summary

• Use shutil.disk_usage() to get total, used, and free disk space for any path.
• Convert bytes to gigabytes for easier reading.
• Check multiple mount points to get a complete picture of your storage layout.
• Build automated alerts to catch low disk space conditions early.

With just a few lines of Python, you can replace manual disk checks with a reliable, scriptable solution that fits right into your existing automation workflows.

The shutil.disk_usage() function returns disk space statistics for a given path, showing total, used, and free space in bytes.

📦 Example 1: Check disk space for current directory

Get basic disk usage statistics for the folder you are currently working in.

import shutil

usage = shutil.disk_usage(".")
print(usage)

📤 Output: usage(total=500107862016, used=320456789012, free=179651073004)

📦 Example 2: Extract total disk space in gigabytes

Convert the total bytes returned by disk_usage() into gigabytes for easier reading.

import shutil

usage = shutil.disk_usage("/")
total_gb = usage.total / (1024 ** 3)
print(total_gb)

📤 Output: 465.76

📦 Example 3: Calculate percentage of disk space used

Compute the percentage of disk space currently in use on the root drive.

import shutil

usage = shutil.disk_usage("/")
percent_used = (usage.used / usage.total) * 100
print(percent_used)

📤 Output: 64.08

📦 Example 4: Check free space on a specific drive or mount point

Verify how much free space is available on a specific drive path like /mnt/data.

import shutil

usage = shutil.disk_usage("/mnt/data")
free_gb = usage.free / (1024 ** 3)
print(free_gb)

📤 Output: 120.45

📦 Example 5: Alert if free space is below a threshold

Check if free space on the root drive is less than 10 GB and print a warning for engineers.

import shutil

usage = shutil.disk_usage("/")
free_gb = usage.free / (1024 ** 3)
threshold_gb = 10

if free_gb < threshold_gb:
    print("Warning: Low disk space")
else:
    print("Disk space OK")

📤 Output: Disk space OK

📊 Quick Reference Table

Understanding how much disk space is available on a system is a fundamental task for any engineer working with servers or applications. Before you can move files, create backups, or deploy new software, you need to know how much room you have to work with. Python provides a simple and reliable way to check disk space using the shutil module, which gives you detailed information about the physical storage layout of your system.

⚙️ Why Check Disk Space?

• Prevent failures – Running out of disk space can crash applications or prevent log files from being written.
• Plan capacity – Knowing current usage helps you decide when to add more storage or clean up old files.
• Automate monitoring – You can write scripts that alert you when disk usage crosses a threshold.
• Verify mounts – Ensure external drives, network shares, or cloud volumes are properly attached and accessible.

📊 The Key Function: shutil.disk_usage()

The shutil module includes a function called disk_usage() that takes a path as input and returns a named tuple with three important values:

• total – The total disk space on the drive or partition, in bytes.
• used – The amount of space currently in use, in bytes.
• free – The amount of space still available, in bytes.

You call it by passing a path string to the function, like shutil.disk_usage("/") for the root drive on Linux or shutil.disk_usage("C:\") on Windows.

🛠️ How to Use It in a Script

Here is a simple example of how you might check disk space in a Python script:

• First, import the shutil module.
• Then, call shutil.disk_usage() with the path you want to inspect.
• Store the result in a variable, such as usage.
• Access the values using usage.total, usage.used, and usage.free.

To make the output human-readable, you can convert bytes to gigabytes by dividing by 1024 three times (bytes to kilobytes, kilobytes to megabytes, megabytes to gigabytes). A common approach is to define a helper function that does this conversion automatically.

📋 Comparison: Bytes vs. Human-Readable Format

Engineers almost always work with human-readable formats because raw byte values are too large to interpret quickly.

🕵️ Checking Multiple Drives or Mount Points

In many environments, you will have multiple drives or partitions. You can check each one by calling disk_usage() with different paths:

• For the root drive: shutil.disk_usage("/")
• For a data drive mounted at /data: shutil.disk_usage("/data")
• For a backup drive at /mnt/backup: shutil.disk_usage("/mnt/backup")

You can loop through a list of paths and print the disk usage for each one, making it easy to monitor an entire server with a single script.

⚠️ Important Notes for Engineers

• Path must exist – If the path you pass to disk_usage() does not exist, Python will raise a FileNotFoundError. Always verify the path first.
• Permissions matter – On some systems, you may need elevated privileges to query certain drives or partitions.
• Cross-platform – The shutil.disk_usage() function works on Windows, macOS, and Linux, making it a reliable choice for scripts that run on multiple operating systems.
• Real-time values – The values returned are a snapshot at the moment the function is called. Disk usage can change rapidly on busy systems.

🧪 Practical Use Case: Alerting on Low Disk Space

A common pattern is to check disk space and send an alert if free space drops below a certain threshold. For example:

• Define a threshold, such as 10 GB.
• Call shutil.disk_usage() for the root drive.
• Compare usage.free to your threshold.
• If free space is below the threshold, print a warning or log the event.

This kind of check can be scheduled to run every hour using a cron job or task scheduler, giving you early warning before disk space becomes a critical issue.

✅ Summary

• Use shutil.disk_usage() to get total, used, and free disk space for any path.
• Convert bytes to gigabytes for easier reading.
• Check multiple mount points to get a complete picture of your storage layout.
• Build automated alerts to catch low disk space conditions early.

With just a few lines of Python, you can replace manual disk checks with a reliable, scriptable solution that fits right into your existing automation workflows.

The shutil.disk_usage() function returns disk space statistics for a given path, showing total, used, and free space in bytes.

📦 Example 1: Check disk space for current directory

Get basic disk usage statistics for the folder you are currently working in.

import shutil

usage = shutil.disk_usage(".")
print(usage)

📤 Output: usage(total=500107862016, used=320456789012, free=179651073004)

📦 Example 2: Extract total disk space in gigabytes

Convert the total bytes returned by disk_usage() into gigabytes for easier reading.

import shutil

usage = shutil.disk_usage("/")
total_gb = usage.total / (1024 ** 3)
print(total_gb)

📤 Output: 465.76

📦 Example 3: Calculate percentage of disk space used

Compute the percentage of disk space currently in use on the root drive.

import shutil

usage = shutil.disk_usage("/")
percent_used = (usage.used / usage.total) * 100
print(percent_used)

📤 Output: 64.08

📦 Example 4: Check free space on a specific drive or mount point

Verify how much free space is available on a specific drive path like /mnt/data.

import shutil

usage = shutil.disk_usage("/mnt/data")
free_gb = usage.free / (1024 ** 3)
print(free_gb)

📤 Output: 120.45

📦 Example 5: Alert if free space is below a threshold

Check if free space on the root drive is less than 10 GB and print a warning for engineers.

import shutil

usage = shutil.disk_usage("/")
free_gb = usage.free / (1024 ** 3)
threshold_gb = 10

if free_gb < threshold_gb:
    print("Warning: Low disk space")
else:
    print("Disk space OK")

📤 Output: Disk space OK

📊 Quick Reference Table