VizDisk

VizDisk is a lightweight tool that visualizes your disk usage as an interactive tree map. It uses ncdu to scan directories efficiently and serves a D3.js visualization in your browser.

Why Vizdisk?

I wanted something like WinDirStat / WizTree, but with a modern interface and the ability to run it on a headless server. It’s basically a quick "what’s eating my disk?" dashboard for a homeserver that I can open in a browser.

Features

• Fast Scanning: Leverages ncdu for efficient disk usage analysis.
• Interactive UI: Explore directories and files using a D3.js tree visualization.
• Docker Support: Run it anywhere without installing Go or ncdu on your host.
• Single Binary: Compiles to a static binary with embedded assets.

Screenshots

Map View

List View

Prerequisites

For Local Execution

• Go (1.24+)
• ncdu
  • Ubuntu/Debian: sudo apt install ncdu
  • macOS: brew install ncdu

For Docker Execution

• Docker

Quickstart (Docker)

VizDisk scans whatever is mounted at /scan inside the container.

By default, the examples below bind the web UI to 127.0.0.1 (localhost) for safety. If you want it accessible from your LAN, remove the 127.0.0.1: prefix in the port mapping.

Docker Compose

Create a compose.yml:

services:
    vizdisk:
        image: ghcr.io/jimzical/vizdisk:latest
        ports:
            - "127.0.0.1:8810:8810"
        volumes:
            # Mount the directory you want to scan to /scan in the container.
            # Example: scan your whole machine (read-only):
            - "/:/scan:ro"
            # Example: scan only your home folder (read-only):
            # - "/home:/scan:ro"
            # Example (macOS):
            # - "/Users:/scan:ro"
        environment:
            # Optional: change the HTTP port the server listens on.
            # If you change this, also update the host-side port mapping above.
            NCDU_PORT: "8810"

Start it:

docker compose -f compose.yml up

Open http://localhost:8810.

To scan a different folder, edit the volume mapping in compose.yml (mount your target directory to /scan:ro).

Docker (one-liner)

Scan your whole machine (read-only):

docker run --rm -p 127.0.0.1:8810:8810 -v /:/scan:ro ghcr.io/jimzical/vizdisk:latest

Scan only your home directory (read-only):

docker run --rm -p 127.0.0.1:8810:8810 -v $HOME:/scan:ro ghcr.io/jimzical/vizdisk:latest

Remote access (SSH port-forward)

If VizDisk is running on a remote server and you’re connected via SSH, you can tunnel it to your laptop:

ssh -L 8810:127.0.0.1:8810 user@your-server

Then open http://localhost:8810 on your laptop.

Installation

Option 1: Download Binary

Download the latest binary for your OS from the Releases Page.

Note: The downloaded binary still requires ncdu to be installed (see Prerequisites → For Local Execution).

Option 2: Build from Source

git clone https://github.com/jimzical/vizdisk.git
cd vizdisk
go build -o vizdisk main.go

Usage

Running Locally

# Scan the current directory
./vizdisk

# Or scan a specific directory
./vizdisk /path/to/scan

The browser should open automatically at http://localhost:8810.

Building a Docker Image Locally

docker build -t vizdisk:local .
docker run --rm -p 127.0.0.1:8810:8810 -v $(pwd):/scan:ro vizdisk:local

Configuration

You can configure the port using an environment variable:

• NCDU_PORT: Sets the HTTP server port (default: 8810).

Example:

export NCDU_PORT=9090
go run main.go

TODOs

• Update screenshots in README.md
• Add basic authentication to restrict access
• Add ability to restrict to localhost only (bind host option)
• Add filtering options (e.g., exclude certain file types or directories)
• Add option to export reports (e.g., CSV, JSON)
• Add a scan progress indicator / "scanning..." status
• Cache scan results (avoid re-scanning on every page refresh)
• Add an option to rescan on demand