ncdu-reader
Table of Contents
What is it?
ncdu-reader is a parser for binary exports generated by NCDU available since 2.6.
Usage
In order to parse a binary export generated by NCDU (i.e., ncdu -O export.bin), you can use the ncdu_reader.ncdu module.
from ncdu_reader import ncdu
export_path = "/tmp/export.bin"
root = ncdu.parse_ncdu(export_path)
For a simple file structure like this:
/tmp/ncdu-playground
└── foo
├── bar
│ ├── qux
│ └── quxx.bin
└── baz.bin
You will get this kind of output:
Parsed output
Directory(reference=AbsoluteReference(block_index=0, offset=126),
name='/tmp/ncdu-playground',
type=<ItemType.Directory: 0>,
prev=None,
asize=4096,
dsize=4096,
uid=None,
gid=None,
mode=None,
mtime=None,
dev=2096,
rderr=None,
cumasize=16384,
cumdsize=16384,
shrasize=0,
shrdsize=0,
items=5,
sub=RelativeReference(offset=-29),
children=[Directory(reference=AbsoluteReference(block_index=0,
offset=97),
name='foo',
type=<ItemType.Directory: 0>,
prev=None,
asize=4096,
dsize=4096,
uid=None,
gid=None,
mode=None,
mtime=None,
dev=0,
rderr=None,
cumasize=12288,
cumdsize=12288,
shrasize=0,
shrdsize=0,
items=4,
sub=RelativeReference(offset=-20),
children=[File(reference=AbsoluteReference(block_index=0,
offset=77),
name='baz.bin',
type=<ItemType.File: 1>,
prev=RelativeReference(offset=-29),
asize=0,
dsize=0,
uid=None,
gid=None,
mode=None,
mtime=None),
Directory(reference=AbsoluteReference(block_index=0,
offset=48),
name='bar',
type=<ItemType.Directory: 0>,
prev=None,
asize=4096,
dsize=4096,
uid=None,
gid=None,
mode=None,
mtime=None,
dev=0,
rderr=None,
cumasize=8192,
cumdsize=8192,
shrasize=0,
shrdsize=0,
items=2,
sub=RelativeReference(offset=-21),
children=[File(reference=AbsoluteReference(block_index=0,
offset=27),
name='quxx.bin',
type=<ItemType.File: 1>,
prev=RelativeReference(offset=-27),
asize=0,
dsize=0,
uid=None,
gid=None,
mode=None,
mtime=None),
Directory(reference=AbsoluteReference(block_index=0,
offset=0),
name='qux',
type=<ItemType.Directory: 0>,
prev=None,
asize=4096,
dsize=4096,
uid=None,
gid=None,
mode=None,
mtime=None,
dev=0,
rderr=None,
cumasize=4096,
cumdsize=4096,
shrasize=0,
shrdsize=0,
items=0,
sub=None,
children=[])])])])
For more information about what the different fields mean, refer to the official documentation.
Partial reads
ncdu-reader does not support lazily reading exports (e.g., parsing the root at first and then parsing children when requested). This means that the entire tree needs to be parsed at once. This can be problematic for very large exports.
It is however possible to only parse down to a certain depth, e.g. ncdu.parse_ncdu(export_path, depth=4). If all you care about is getting information about the top-level item (i.e., the root of your export), pass a depth of 0.
Performance
Here is a very unscientific benchmark of parsing exports for varying tree sizes to give an idea of scale, not expected performance. This includes the startup time for the Python interpreter, hence why small exports take around the same time.
| Tree Size | Time (mean ± σ) |
|---|---|
| 5 | 93.0 ms ± 1.6 ms |
| 12,605 | 95.1 ms ± 3.0 ms |
| 1,064,009 | 7.708 s ± 0.114 s |
| 7,905,281 | 87.761 s ± 0.710 s |
Note that RAM availability greatly impacts parsing of larger exports.
License
ncdu-reader is distributed under the terms of the MIT license.
1 maintainer
Metadata
1 maintainer
Release files for ncdu-reader 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ncdu_reader-1.0.0.tar.gz | 18.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ncdu_reader-1.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 29.7 kB
Release files / ncdu_reader-1.0.0.tar.gz
| Download URL | ncdu_reader-1.0.0.tar.gz |
|---|---|
| Size | 18.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c23a533b79a8ea07af5f98b809828c7ce9e91c0fe5c57b79408b49daa0446e1b
|
|
BLAKE2b-256 checksum How to use checksums |
f7be1db68fef4aca1dab5da528b89dbfa73fa4710c4485af225da41e1d86cacc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / ncdu_reader-1.0.0-py3-none-any.whl
| Download URL | ncdu_reader-1.0.0-py3-none-any.whl |
|---|---|
| Size | 11.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8466eae7c70d74a3992dcce904ac8c9eb4c280d1ba64edf780df589d7680e0f7
|
|
BLAKE2b-256 checksum How to use checksums |
1f34a95e71791e8dd9a7433245a842629d4198d0765ae52f2b950003863f9f40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
