Skip to main content

Walk file systems and collect stats

Project description

Walk file systems and collect stats.


Statwalker is a command-line program that scan files recursively (normally called as “walk”) and collects stats, basically file names and metadata (inode information in Linux systems). It runs in parallel in a single machine, and the output is a comma-separated file (csv), one line per file. These results can be analysed using other tools (see below).


The csv file will look like this:


Column description:

  1. INODE: device identifier and inode (Linux)
  2. ATIME: last access time in unix format (seconds since epoc)
  3. MTIME: last modified time in unix fromat
  4. UID: user ID
  5. GID: group ID
  6. MODE: mode, which is file type and permissions
  7. SIZE: real size in bytes, same value reported with command du -b
  8. DISK: disk usage, which is number of blocks times 512
  9. PATH: full path

As noticed, the information is not very human readable, for performance reasons. A tool is available in the source folder called, that I use to translate that file into a more useful version. This resolved file will look like this (this time the columns are self-documented by the name, with size and disk in GB):


How it works

Collecting stats is as simple as this one-liner in bash:


There are many tools doing the same thing, the problem is performance. After trying some tools in a file system with many terabytes of data and millions of files, the problem became untractable. I run statwalker in a storage with 100+ millions of files, with a reading rate over NFS folders of 3000 files/second on average, and much faster if disks are local.


Use pip:

$ pip install statwalker


Run it from the command line:

$ statwalker -h

usage: [-h] [-b BALANCE] [-c] [-n PROCESSES] [-o OUTPUT]
                     [--skip SKIP] [--sort]

positional arguments:
  PATH                  path to walk and get stats

optional arguments:
  -h, --help            show this help message and exit
  -b BALANCE, --balance BALANCE
                        balance workload in task assignment
  -c, --color           cancel colors
  -n PROCESSES, --processes PROCESSES
                        number of processes to run in parallel
  -o OUTPUT, --output OUTPUT
                        csv file to write stats
  --skip SKIP           skip file name pattern list, separated by comma
  --sort                sort results

You can experiment and compare results with different options, for example:

$ statwalker /path -b7

/*************** *************************************/
Command: statwalker /path -b7
Input: /path
Output: /home/user/home-user-apps.csv
Balance: 7
Running with 4 processes...
Pre-process:            0.15 sec
PID: 18239              0.2 sec [=======   ] 70.62% [24365 files]
PID: 18240              0.2 sec [======    ] 63.31% [27524 files]
PID: 18241              0.2 sec [=======   ] 78.06% [33920 files]
PID: 18242              0.2 sec [========  ] 82.98% [34471 files]
Total files by workers: 120280
Folder with max files:  /path/folder_with_many_files [3720 files]
Folder with max size:   /path/big_file [1.0GB]
Avg time by workers:    0.2 sec
Difference (Max-Min):   19.66%
Work balance Ok.
Post-process:           0.0 sec [2793 files]
Total files:            2793
Total time spent:       0.43 sec [0:00:00.427657]
Rate:                   6530 files/sec
Output: path.csv [338.6KB]


Clone the github repository:

$ git clone


Add documentation for analysis tools: resolution, aggregation, plots, benchmark with c++ and mpi versions.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for statwalker, version 1.0
Filename, size File type Python version Upload date Hashes
Filename, size statwalker-1.0.tar.gz (7.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page