mkpfs-tui

A Textual terminal UI for mkpfs — pack, inspect, verify, tree, and unpack PlayStation PFS images from a single sidebar-driven app. Every operation has its own view with file/directory pickers, live progress, and a result panel that surfaces warnings and errors without ever leaving the terminal.

mkpfs-tui is a third-party frontend. It pins mkpfs as a dependency and never modifies it.

Contents: Screenshots · Operations · Requirements · Install · Usage · Contributing · License

Operations

Screenshots

About — the welcome screen:

Pack — build an image from a folder or file:

Inspect — header, counts, sizes, and checksums:

Verify — structure / checksum checks with a PASS/FAIL banner:

Tree — browse the file tree stored inside an image:

Requirements

• Python 3.11 or newer (only needed for the uvx/pipx install; the Linux binary bundles its own).
• A terminal that renders modern TUIs. Most do; on Windows use Windows Terminal (the default on Windows 11), not the legacy console.
• mkpfs is installed automatically as a dependency — you do not install it yourself.

Install

Prefer a self-contained download? Grab a build from the Releases page.

The cross-platform way is via Python, using either uv (recommended — uvx runs it without installing) or pipx (installs the mkpfs-tui command).

Linux

# Prerequisite — uv (one line, no root):
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run it (downloads + runs in an isolated env, nothing to clean up):
uvx mkpfs-tui

Or with pipx — sudo apt install pipx (Debian/Ubuntu) / sudo pacman -S python-pipx (Arch), then:

pipx ensurepath        # once, then restart the shell
pipx install mkpfs-tui
mkpfs-tui

No Python? Download mkpfs-tui-linux-x86_64.tar.gz from the Releases page, then:

tar -xzf mkpfs-tui-linux-x86_64.tar.gz
./mkpfs-tui/mkpfs-tui

macOS

# Prerequisite — uv (via Homebrew or the install script):
brew install uv          # or: curl -LsSf https://astral.sh/uv/install.sh | sh

uvx mkpfs-tui

Or with pipx: brew install pipx && pipx ensurepath, then pipx install mkpfs-tui. (No prebuilt macOS binary yet — use the Python install above.)

Windows

Use Windows Terminal for a TUI. In PowerShell:

# Prerequisite — uv:
winget install --id=astral-sh.uv  # or: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uvx mkpfs-tui

Or with pipx: py -m pip install --user pipx, then py -m pipx ensurepath (restart the terminal) and pipx install mkpfs-tui. (No prebuilt Windows binary yet — use the Python install above.)

Usage

Launch the app (uvx mkpfs-tui, or mkpfs-tui if installed). You land on the Pack view.

The interface

• Left sidebar — the five operations. Move with ↑/↓; the right pane switches as you go.
• Right pane — the selected operation's form, run button, progress, and a result panel (errors in red, warnings in amber, success in green).
• Browse… buttons open a file/directory picker — navigate with the arrows, Choose to accept, Cancel/Escape to dismiss. You can also just type a path into the field.

Keyboard

By operation

• Pack — choose Folder or File mode, pick the Source and the Output image path (the image is written exactly to the path you type — include the extension you want), then set options: PS4/PS5 version, inode width (folder mode only), compression level, CPU count, block size, and the switches (Compress, Case-insensitive, Signed, Encrypted, Dry run, Verify after). Press Pack to watch a live progress bar; Cancel stops the build. If the output already exists you'll be asked to confirm before it's overwritten.
• Inspect — point at an Image and press Inspect; the table fills with version, sizes, counts, and checksums.
• Verify — give an Image and, optionally, a Source directory and/or an expected CRC32 / manifest SHA-256, then press Verify for a PASS/FAIL banner plus any errors.
• Tree — pick an Image and press Build tree to browse its contents.
• Unpack — pick an Image and an Output directory and press Unpack. Turn on Overwrite to clear a non-empty output directory first (you'll be asked to confirm the deletion).

Encrypted images

Every view has an EKPFS key field (64 hex characters) and a newCrypt switch for encrypted images; leave them blank/off for unencrypted ones. In Pack, the key is only applied when Encrypted is on.

Contributing

Issues and PRs are welcome. The project uses uv for everything.

Set up

git clone https://github.com/ClaudioVarandas/mkpfs-tui
cd mkpfs-tui
uv sync                                              # creates .venv with deps + dev tools
uv run textual run --dev mkpfs_tui.app:MkpfsTuiApp   # run the app (or: uv run python -m mkpfs_tui)

Tip: run uv run textual console in a second pane to see logs/tracebacks from the --dev app.

Test & lint

./run-tests.sh        # ruff format + ruff check --fix + pytest (what to run before committing)
uv run pytest         # tests only

Tests use Textual's App.run_test() Pilot harness with pytest-asyncio in auto mode. CI runs lint + tests (check-mode) on every push and PR.

Conventions

• uv only — uv sync, uv run …; never pip or a global Python.
• Type hints everywhere, Google-style docstrings, from __future__ import annotations at the top of every module, prefer X | None over Optional. ruff is law (config in pyproject.toml).
• The mkpfs boundary (most important rule): all imports of and calls to mkpfs.* live in the single module mkpfs_tui/mkpfs_runner.py, which exposes the app's own value types. No other module imports mkpfs. When you depend on new mkpfs surface, add an assertion to tests/test_mkpfs_contract.py so an upstream change fails loudly.
• Updating the pinned mkpfs: uv lock --upgrade-package mkpfs, run the tests (including the contract test), then commit.

See CHANGELOG.md for release history. The architecture and the per-milestone build plans are kept outside the repo (in the author's planning notes).

License

GPL-3.0-or-later. mkpfs-tui imports mkpfs, which is GPLv3, so the combined work is GPL.