DiskSpace

Hi everyone, I needed this for a project I’ve been working on, and couldn’t find a simple solution that would work. The solutions in Check disk space inside elixir didn’t work for me.

Looking at how Exqlite deals with NIFs, I wrote a Makefile and then used Grok 3 with numerous rounds to generate the C file for a NIF. I then had GPT-5 and Gemini 2.5 Flash review it, then back to Grok 3 for implementing the suggested improvements, as Grok’s license permits licensing generated code permissively. Back and forth, again and again.

It should work on everything POSIX and on Windows, though I have only tested it on Debian 12. I don’t have Apple computers, and currently don’t run FreeBSD or NetBSD anywhere to try it out there.

What it does

It returns information about total, used, free, and available disk space, using native system calls for accuracy and performance. Optionally converts the results into human-readable strings with kibibytes etc. or kilobytes etc.

Returns disk space metrics as a map with keys:

• :total — total size of the filesystem
• :used — bytes currently used
• :free — bytes free on the filesystem
• :available — bytes available to the current user (may be less than free due to permissions)

Provides both safe (stat/2) and bang (stat!/2) variants (with opts keyword-list options for human-readable output), the latter raising on errors.

Provides a humanize/2 function to which you can pipe the output of stat/2 and stat!/2 to generate human-readable output, if you don’t want to pass opts to those functions.

Usage example

iex(1)> DiskSpace.stat!("/tmp")
%{
  available: 32389640192,
  free: 43895349248,
  total: 225035927552,
  used: 181140578304
}
iex(2)> DiskSpace.stat("/tmp")
{:ok,
 %{
   available: 32389599232,
   free: 43895308288,
   total: 225035927552,
   used: 181140619264
 }}
iex(3)> DiskSpace.stat("/tmp", humanize: true)
{:ok,
 %{
   available: "30.17 GiB",
   free: "40.88 GiB",
   total: "209.58 GiB",
   used: "168.70 GiB"
 }}
iex(4)> DiskSpace.stat("/tmp", humanize: true, base: :decimal)
{:ok,
 %{
   available: "32.39 GB",
   free: "43.90 GB",
   total: "225.04 GB",
   used: "181.14 GB"
 }}
iex(5)> DiskSpace.stat!("/yolo/swag")
** (DiskSpace.Error) DiskSpace error: :realpath_failed
    (disk_space 0.1.0) lib/disk_space.ex:86: DiskSpace.stat!/2
    iex:5: (file)

Error-handling

• stat/2 returns {:ok, stats_map} or {:error, reason}
• stat!/2 returns stats_map or raises DiskSpace.Error

Reporting issues and opening PRs welcome.

• Package: disk_space | Hex
• Documentation: README — DiskSpace v1.0.0
• License: Apache-2.0
• Git repo: