A small Elixir library with a NIF in Rust for getting disk usage statistics for a given filesystem path.

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

Features

• 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 ) functions, the latter raising DiskSpace.Error on errors
• Optional conversion of results from bytes into human-readable strings (in kB, KiB, etc.) with a keyword-list option that calls humanize/2
• Supports Linux, macOS, Windows, NetBSD, FreeBSD, OpenBSD, DragonFlyBSD

Installation

Add disk_space to your list of dependencies in mix.exs:

def deps do
  [
    {:disk_space, "~> 1.0.0"}
  ]
end

Usage examples

iex(1)> DiskSpace.stat!("/tmp")
%{
  free: 39917449216,
  total: 225035927552,
  used: 185118478336,
  available: 28411740160
}
iex(2)> DiskSpace.stat("/tmp")
{:ok,
 %{
   free: 39917436928,
   total: 225035927552,
   used: 185118490624,
   available: 28411727872
 }}
iex(3)> DiskSpace.stat("/tmp", humanize: :binary)
{:ok,
 %{
   free: "37.18 GiB",
   total: "209.58 GiB",
   used: "172.41 GiB",
   available: "26.46 GiB"
 }}
iex(4)> DiskSpace.stat("/tmp", humanize: :decimal)
{:ok,
 %{
   free: "39.92 GB",
   total: "225.04 GB",
   used: "185.12 GB",
   available: "28.41 GB"
 }}
 iex(5)> DiskSpace.stat("/home/tisaak") |> DiskSpace.humanize()
{:ok,
 %{
   free: "37.18 GiB",
   total: "209.58 GiB",
   used: "172.41 GiB",
   available: "26.46 GiB"
 }}
iex(6)> DiskSpace.stat("/home/tisaak") |> DiskSpace.humanize(:decimal)
{:ok,
 %{
   free: "39.92 GB",
   total: "225.04 GB",
   used: "185.12 GB",
   available: "28.41 GB"
 }}
iex(7)> DiskSpace.stat("/yolo/swag")
{:error,
 %{
   info: %{errno: 2, errstr: "No such file or directory (os error 2)"},
   reason: :not_directory
 }}
iex(8)> DiskSpace.stat!("/yolo/swag")
** (DiskSpace.Error) DiskSpace error: %{info: %{errno: 2, errstr: "No such file or directory (os error 2)"}, reason: :not_directory}
    (disk_space 1.0.0) lib/disk_space.ex:84: DiskSpace.stat!/2
    iex:8: (file)

Usage trick

In case you want to get results for a path that doesn’t yet exist:

  def recursively_check_disk_space(local_dir) when is_binary(local_dir) do
    local_dir |> Path.split() |> Enum.reduce_while(local_dir, fn _, acc ->
      case DiskSpace.stat(acc) do
        {:ok, info} -> {:halt, {:ok, info}}
        {:error, _} ->
          {:cont, acc |> Path.split() |> Enum.reverse() |> tl |> Enum.reverse() |> Path.join()}
      end
    end)
  end

This is pulled from my book Elixir File Browsing , in which the API client for the undocumented REST API of File Browser uses DiskSpace to check whether there is enough space on the target local path’s mount point before downloading a resource from the server.

Error handling

• stat/2 returns {:ok, stats_map} or {:error, info}, where info is a map with populated :reason (atom) and :info (map or nil) with more information, if provided by the NIF.
• stat!/2 returns stats_map or raises DiskSpace.Error with the {:error, info} of stat/2 as the message.

Supported Elixir and OTP versions

In short:

• Tested and confirmed working on Elixir 1.14 (OTP 25) to 1.18 (OTP 27)
• Tested and confirmed working on Linux, Windows and the BSDs (amd64)
• Tested and confirmed working on macOS (arm64)
• Reported as also working on Elixir 1.18.4 (OTP 28), at least on macOS/arm64

Build & test matrix

See also: GitHub Actions for Linux, macOS, Windows.

Build requirements

Generally: Erlang development headers (for erl_nif functions), Rust.

Linux (amd64)

• erlang-dev or erlang-erts-dev (Erlang development headers)
• libc development headers (usually installed by default)
• rustc

Example on Debian and its derivatives:

sudo apt-get install elixir erlang-dev rustc

macOS (arm64)

xcode-select --install

• clang
• Erlang installed via Homebrew or other means

NetBSD (amd64)

✅ Tested on version 10.1 with Elixir 1.17.2, OTP 27.

pkgin update
pkgin install erlang elixir rust

FreeBSD (amd64)

✅ Tested on version 14.3 with Elixir 1.17.3, OTP 26.

pkg update
pkg install erlang elixir ca_root_nss rust

DragonFlyBSD (amd64)

✅ Tested on version 6.4.2 with Elixir 1.16.3, OTP 25.

pkg update
pkg install erlang elixir rust

OpenBSD (amd64)

✅ Tested on version 7.7 with Elixir 1.18.3, OTP 27.

pkg_add erlang-27.3.3v0 elixir-1.18.3 rust

Windows (amd64)

1. Install Erlang/OTP with development headers:

   • Download the official installer from https://www.erlang.org/downloads (choose the latest stable version).
   • During installation, ensure “Development and debugging tools” is selected (this includes headers like erl_nif.h).
   • Add the Erlang bin directory to your PATH (e.g., C:\Program Files\erl-27.0\bin).

2. Install Elixir:

   • Download the installer from https://elixir-lang.org/install.html#windows .
   • Follow the instructions to add Elixir to your PATH.

3. Install Visual Studio Build Tools (required for Rust’s MSVC toolchain):

   • Download from https://visualstudio.microsoft.com/downloads/ (under “Tools for Visual Studio”, select “Build Tools for Visual Studio”).
   • Run the installer and select the “C++ build tools” workload (includes MSVC compiler and linker).
   • No full Visual Studio IDE is needed—just the build tools.

4. Install Rust:

   • Download rustup-init.exe from https://www.rust-lang.org/tools/install .
   • Run it and select the default options, which install the stable MSVC toolchain (stable-x86_64-pc-windows-msvc).
   • Add Rust to your PATH if prompted (cargo and rustc should be accessible from the command line).

Alternatives

Add :os_mon in :extra_applications in mix.exs, then use get_disk_info/1 of disksup service.

Comparison to alternatives

Use of GenAI

The following files were incrementally generated/adapted by xAI’s Grok 4 model over multiple rounds of prompting for reviews and improvements that were suggested by Grok 4, GPT-5 and Gemini 2.5 Pro, and according to the warnings/errors of the GitHub Actions workflow across Linux, macOS, and Windows:

• lib.rs
• Cargo.toml
• build.yml

License

Apache-2.0

Documentation

For more details, see the documentation at https://hexdocs.pm/disk_space .

Related

• DiskSpace - retrieve disk usage statistics for a given filesystem path – thread on ElixirForum
• I let better LLMs write an Elixir NIF in Rust; it worked pretty well – blog post related to version 1.0.0 that relies on Rust code generated by Grok 4 with code reviews by GPT-5 and Gemini 2.5 Pro, plus my thoughts on vibe-coding
• I let LLMs write an Elixir NIF in C; it mostly worked – blog post related to versions up to 0.4.0 that relied on C code generated by Grok 3 with code reviews by GPT-5 and Gemini 2.5 Flash
• Comments on HackerNews that spurred me to re-vibe-code it in Rust with Grok 4, as running splint on the original C code revealed numerous memory-safety issues