Dissect Utilities (dissect-util)

3.24 · active · verified Fri Apr 17

Dissect.util (dissect-util on PyPI) is a module within the Dissect forensics framework, providing a collection of essential utility functions. It offers functionalities for humanizing data (e.g., bytes, time), robust JSON serialization and deserialization, typecasting, progress bars, and packaging introspection. It is currently at version 3.24 and receives regular updates as part of the broader Dissect project.

Common errors

```
ModuleNotFoundError: No module named 'dissect.util.enum'
```
cause Attempting to import from the old `dissect.util.enum` path after upgrading to dissect-util 3.x.

fix The module was moved. Update your import to `from dissect.enum import ...`.
```
AttributeError: module 'dissect.util' has no attribute 'structures'
```
cause Attempting to use `dissect.util.structures` after upgrading to dissect-util 3.x.

fix The `dissect.util.structures` module was removed in version 3.0.0. You will need to refactor your code to use alternative data structures or utilities.
```
SyntaxError: future feature annotations is not defined
```
cause Running dissect-util 3.x on an unsupported Python version (e.g., Python 3.9 or older).

fix dissect-util >=3.0.0 requires Python 3.10 or higher. Upgrade your Python environment.
```
AttributeError: module 'dissect.util.json' has no attribute 'serialize_msgspec'
```
cause Trying to use `msgspec`-backed JSON functions without installing the optional `msgspec` dependency.

fix Install dissect-util with the `msgspec` extra: `pip install dissect-util[msgspec]`.

Warnings

breaking dissect-util version 3.0.0 and later requires Python 3.10 or higher. Earlier versions supported Python 3.8+.
Fix: Upgrade your Python environment to 3.10 or newer, or pin your dissect-util dependency to <3.0.0 if compatible with other project requirements.
breaking The `dissect.util.enum` module was moved to `dissect.enum` in version 3.0.0, and `dissect.util.structures` was entirely removed. Code relying on these modules will break.
Fix: For `enum`, update imports from `from dissect.util.enum import ...` to `from dissect.enum import ...`. For `structures`, refactor your code as the module has no direct replacement in `dissect.util`.
gotcha Advanced JSON features, such as `msgspec` backend support for faster serialization/deserialization, require installing the `msgspec` optional dependency.
Fix: Install `dissect-util` with the `msgspec` extra: `pip install dissect-util[msgspec]`.

Install

pip install dissect-util Standard installation
pip install dissect-util[msgspec] With optional msgspec JSON backend

Imports

bytes_to_human

from dissect.util.humanize import bytes_to_human

ProgressBar

from dissect.util.progressbar import ProgressBar

serialize
wrong:
```
import dissect.util.json
```
correct:
```
from dissect.util.json import serialize
```
Functions are typically imported directly from submodules, not accessed via top-level `dissect.util.json.serialize`.

Quickstart

This quickstart demonstrates common utility functions from `dissect.util`, including humanizing byte and time values, and using a simple console progress bar.

from dissect.util.humanize import bytes_to_human, time_to_human
from dissect.util.progressbar import ProgressBar
import time

print(f"Humanized bytes: {bytes_to_human(1_234_567_890)}")
print(f"Humanized time: {time_to_human(3600 * 24 * 7 * 3 + 12345)}")

# Example of using a progress bar
print("\nDemonstrating ProgressBar:")
with ProgressBar(total=10) as bar:
    for i in range(10):
        time.sleep(0.1) # Simulate work
        bar.next()
print("Progress bar complete!")

view raw JSON →