diskfreespace()

Introduction to the PHP diskfreespace() Function

The diskfreespace() function returns the number of bytes of free space available on the file system or disk partition that contains a given directory. It is useful when you need to check capacity before writing large files, build server-monitoring dashboards, or warn an admin that storage is running low.

diskfreespace() is simply an alias of disk_free_space() — both names call the exact same C implementation and behave identically. The underscore version is the canonical name in the PHP manual; the no-underscore version exists for backward compatibility. New code should prefer disk_free_space(), but you will still see diskfreespace() in older codebases.

This chapter covers the syntax, the single argument it takes, what it returns, runnable examples, and the common gotchas.

Syntax

diskfreespace(string $directory): float|false

The function takes one required argument and returns the free space as a floating-point number of bytes. A float is used (rather than an int) because modern disks can hold far more bytes than a 32-bit integer can represent. On failure it returns false.

Parameter

• $directory (string, required) — A directory on the file system you want to inspect (for example "/", "C:", or "." for the current directory). PHP measures the partition that this directory lives on, not the size of the directory itself. The path must be a directory; passing a regular file produces a warning and returns false.

Return value

• On success: a float — the number of free bytes on the partition.
• On failure (path does not exist, is not a directory, or is not readable): false, plus an E_WARNING.

Examples

Example 1: Free space on the current partition

The safest portable call uses "." (the current directory), which works on every operating system:

<?php
$bytes = diskfreespace(".");
echo $bytes, " bytes free\n";

The output is a raw byte count, such as:

123456789012 bytes free

Example 2: Format the result as a human-readable size

Raw bytes are hard to read. This helper converts the value to KB / MB / GB / TB:

<?php
function humanSize(float $bytes): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];
    $i = 0;
    while ($bytes >= 1024 && $i < count($units) - 1) {
        $bytes /= 1024;
        $i++;
    }
    return round($bytes, 2) . ' ' . $units[$i];
}

echo humanSize(123456789012); // 114.98 GB

Output:

114.98 GB

Example 3: Check a specific path and handle failure

Always check for false before using the result, because the path may be invalid:

<?php
$path = "/no/such/directory";
$free = @diskfreespace($path);

if ($free === false) {
    echo "Could not read free space for $path";
} else {
    echo "Free: $free bytes";
}

The @ suppresses the warning so you can handle the error gracefully with your own message.

Common gotchas

• It measures the partition, not the folder. Calling diskfreespace("/var/www") reports free space on whatever disk /var/www resides on, not how much that single folder uses.
• Pass a directory, not a file. A file path (e.g. "/etc/hosts") returns false and emits a warning.
• Windows paths. Use a drive letter such as "C:" rather than a Unix-style path.
• Free vs. usable space. On some file systems a portion of "free" space is reserved for the root user, so the figure may differ slightly from what a non-root process can actually use.

Related functions

• disk_free_space() — the canonical name for this exact function.
• disk_total_space() — total capacity of the partition; combine with this function to compute the percentage used.
• filesize() — size of an individual file in bytes.

Conclusion

diskfreespace() returns the free bytes on the partition that holds a given directory and is an alias of disk_free_space(). Use it to monitor storage and guard against writes that would overflow the disk, always check for a false return value, and pair it with disk_total_space() when you need the percentage of space remaining.

Practice