MkPFS

MkPFS is a command-line tool and Python library for building, verifying, inspecting, browsing, and extracting PlayStation FileSystem (PFS) disk images. It works with common image naming conventions such as .ffpfs, .ffpfsc, .pfs, .dat, and .bin, and fits both direct image workflows and PKG or FPKG inner-PFS generation.

Quick Start · Compression Statistics · Installation · Command reference · Development · Related projects · Sponsor

🎯 Why MkPFS

MkPFS is designed to be a clean and practical entry point for PlayStation PFS image workflows:

Create and manage PFS disk images for PlayStation-oriented workflows
Verify structure, payload hashes, layout consistency, and source-tree matches
Inspect image contents quickly with a tree view instead of digging through raw structures
Work with common image extensions such as .ffpfs, .ffpfsc.
Use the generated images with tools like MicroMount and ShadowMountPlus
Build the inner PFS filesystem used inside PKG or FPKG workflows
Use the same core workflow from both the CLI and the Python library
Explore a bundled, source-backed knowledge base for PFS and PKG research

🚀 Quick Start

# Install using pip
pip install mkpfs

# Convert an .exfat or .ffpkg file into a PFSC compressed image .ffpfsc
# NOTE: .ffpfsc is the simplest way to have game-file compression support.
mkpfs pack file --compress --verify ./GAME1234.exfat ./GAME1234.ffpfsc

# Convert a homebrew folder into a PFS image with compression and verification
# WARNING: .ffpfs file only has limited support in ShadowMountPlus
mkpfs pack folder --compress --verify ./GAME1234-app ./GAME1234.ffpfs

# Inspect the generated image
mkpfs inspect ./GAME1234.ffpfs

# Unpack the image back into a folder
mkpfs unpack ./GAME1234.ffpfs ./GAME1234-extracted/

💖 Sponsorship

MkPFS is easier to sustain when users who benefit from it help fund it.

Support helps with:

Ongoing CLI improvements
The Python library and reusable internals
Better test coverage and compatibility work
More documentation, examples, and research notes

Sponsor here:

https://github.com/sponsors/RenanGBarreto

Or donate directly using:

BTC: 141kKRoDpaS6PNC2yxSi8vziDFTmzCnArE
USDT (TRC-20): TQb7bUYSYRmdWgALHCejH33dNij9XyTAnU
USDT (ERC-20): 0x63c0b4b21133c4068375ae7566dafcf1398cf6fb

📊 Compression Statistics

Using the compression from MkPFS, you can have your game files reduced by 40-60%, drastically reducing the size of the image. The PlayStation kernel is already able to read the files natively in the PFSC format with minimal performance impact!

The numbers below are measured from a real homebrew title that previously had 6.5 GB of game files:

Format	Description	Size	Space saved
`.exfat`	Raw game image (exFAT)	~6.5 GB	baseline
`.ffpkg`	Raw game image (UFS)	~6.5 GB	baseline
`.exfat.ffpfsc`	PFSC-compressed wrapper around the exFAT image	~3.4 GB	-47%
`.ffpkg.ffpfsc`	PFSC-compressed wrapper around the UFS image	~3.4 GB	-47%
`.ffpfs`	Source folder packed directly into a PFSC image	~3.5 GB	-46%

Both single-file wrapping (pack file) and folder-based packing (pack folder) produce compressed images of equivalent size, giving you flexibility without sacrificing efficiency.

📦 Installation

Run from a local checkout

Install from PyPI

pip install mkpfs
mkpfs -h

uv sync --group dev
uv run mkpfs -h

Install as a local tool

uv tool install .
mkpfs -h

Build distributables

uv build
uv run --frozen twine check dist/*

Command Reference

MkPFS keeps the command surface focused on the image lifecycle. The CLI currently supports pack, verify, inspect, tree, and unpack.

Top-level CLI

mkpfs [-h] {pack,verify,inspect,tree,unpack} ...

Parameter	Description
`-h`, `--help`	Show the top-level help text and exit.
`pack`	Pack a folder or a single file into a PFS image.
`verify`	Validate image structure and payload checksums.
`inspect`	Inspect image metadata and integrity summary.
`tree`	Print the image tree representation.
`unpack`	Extract files from an image into a destination directory.

`pack`

mkpfs pack [-h] {folder,file} ...

Use pack folder to build from a directory tree, or pack file to treat one file as a virtual single-file tree.

`pack folder`

mkpfs pack folder [-h] [--adjust-output-file-extension | --no-adjust-output-file-extension]
                  [--compress | --no-compress] [--threshold-gain THRESHOLD_GAIN]
                  [--block-size BLOCK_SIZE] [--version {PS4,PS5}] [--inode-bits {32,64}]
                  [--case-sensitive | --case-insensitive] [--cpu-count CPU_COUNT]
                  [--compression-level COMPRESSION_LEVEL] [--signed] [--encrypted]
                  [--ekpfs-key EKPFS_KEY] [--require-game-files] [--verbose]
                  [--dry-run] [--verify] source_dir image_file

Examples:

mkpfs pack folder ./input ./game.ffpfs
mkpfs pack folder ./input ./game.ffpfs --encrypted
mkpfs pack folder ./input ./game.ffpfs --require-game-files --verify

Parameter	Description
`source_dir`	Source app or homebrew folder to pack.
`image_file`	Output image file path.
`-h`, `--help`	Show help and exit.
`--adjust-output-file-extension`	Automatically adjust the output extension to match the detected pack mode. This is the default.
`--no-adjust-output-file-extension`	Keep the requested output file name unchanged.
`--compress`	Enable PFSC block compression. This is the default.
`--no-compress`	Disable PFSC block compression.
`--threshold-gain THRESHOLD_GAIN`	Minimum per-block gain percent required to keep PFSC-compressed blocks. Default: `20`.
`--block-size BLOCK_SIZE`	PFS block size in bytes, or `auto`. Default: `auto`, which resolves to `65536`.
`--version {PS4,PS5}`	PFS profile version. Default: `PS4`.
`--inode-bits {32,64}`	Inode width mode bit. Default: `32`.
`--case-sensitive`	Build a case-sensitive image.
`--case-insensitive`	Set the case-insensitive mode bit. This is the default behavior.
`--cpu-count CPU_COUNT`	Number of CPU cores to use for PFSC compression. `0` means auto `max(1, cpu_count())`, non-zero uses `max(1, user value)`.
`--compression-level COMPRESSION_LEVEL`	Zlib compression level from `0` to `9`. Default: `7`.
`--signed`	Build a signed PFS image using a zero EKPFS key and seed.
`--encrypted`	Encrypt filesystem blocks with AES-XTS.
`--ekpfs-key EKPFS_KEY`	Optional 64-hex EKPFS key. When omitted with `--encrypted`, MkPFS uses an all-zero key.
`--require-game-files`	Require `sce_sys/param.json` and `eboot.bin` before packing.
`--verbose`	Print verbose per-file decisions during packing.
`--dry-run`	Scan, layout, and report only. Do not write an image file.
`--verify`	Run `mkpfs verify` automatically after a successful pack.

Notes:

Folder output names are adjusted automatically by default.
MkPFS chooses .ffpfs when sce_sys/param.json exposes a title ID, otherwise it falls back to .ffpfsc.
--ekpfs-key is only meaningful when used with --encrypted.

`pack file`

mkpfs pack file [-h] [--adjust-output-file-extension | --no-adjust-output-file-extension]
                [--compress | --no-compress] [--threshold-gain THRESHOLD_GAIN]
                [--block-size BLOCK_SIZE] [--version {PS4,PS5}] [--inode-bits {32,64}]
                [--case-sensitive | --case-insensitive] [--cpu-count CPU_COUNT]
                [--compression-level COMPRESSION_LEVEL] [--signed] [--encrypted]
                [--ekpfs-key EKPFS_KEY] [--verbose] [--dry-run] [--verify]
                source_file image_file

Examples:

mkpfs pack file ./payload.exfat ./payload.ffpfsc
mkpfs pack file ./payload.exfat ./payload.ffpfsc --verify

Parameter	Description
`source_file`	Single source file to pack.
`image_file`	Output image file path.
`-h`, `--help`	Show help and exit.
`--adjust-output-file-extension`	Automatically adjust the output extension to match the detected pack mode. This is the default.
`--no-adjust-output-file-extension`	Keep the requested output file name unchanged.
`--compress`	Enable PFSC block compression. This is the default.
`--no-compress`	Disable PFSC block compression.
`--threshold-gain THRESHOLD_GAIN`	Minimum per-block gain percent required to keep PFSC-compressed blocks. Default: `20`.
`--block-size BLOCK_SIZE`	PFS block size in bytes, or `auto`. Default: `auto`, which resolves to `65536`.
`--version {PS4,PS5}`	PFS profile version. Default: `PS4`.
`--inode-bits {32,64}`	Inode width mode bit. Default: `32`.
`--case-sensitive`	Build a case-sensitive image.
`--case-insensitive`	Set the case-insensitive mode bit. This is the default behavior.
`--cpu-count CPU_COUNT`	Number of CPU cores to use for PFSC compression. `0` means auto `max(1, cpu_count())`, non-zero uses `max(1, user value)`.
`--compression-level COMPRESSION_LEVEL`	Zlib compression level from `0` to `9`. Default: `7`.
`--signed`	Build a signed PFS image using a zero EKPFS key and seed.
`--encrypted`	Encrypt filesystem blocks with AES-XTS.
`--ekpfs-key EKPFS_KEY`	Optional 64-hex EKPFS key. When omitted with `--encrypted`, MkPFS uses an all-zero key.
`--verbose`	Print verbose per-file decisions during packing.
`--dry-run`	Scan, layout, and report only. Do not write an image file.
`--verify`	Run `mkpfs verify` automatically after a successful pack.

Notes:

Single-file packing stages the file in a temporary one-file tree using links, so the source payload is not duplicated on disk.
The default adjusted extension for single-file output is .ffpfsc.

`verify`

mkpfs verify [-h] [--source-dir SOURCE_DIR | --source-file SOURCE_FILE]
             [--expect-crc32 EXPECT_CRC32]
             [--expect-manifest-sha256 EXPECT_MANIFEST_SHA256]
             [--ekpfs-key EKPFS_KEY] [--new-crypt] image_file

Examples:

mkpfs verify ./game.ffpfs
mkpfs verify ./single.ffpfsc --source-file ./payload.exfat
mkpfs verify ./game.ffpfs --source-dir ./input --expect-crc32 0x7F528D1F

Parameter	Description
`image_file`	Path to the input `.ffpfs` image.
`-h`, `--help`	Show help and exit.
`--source-dir SOURCE_DIR`	Optional source folder for hierarchy and payload comparison.
`--source-file SOURCE_FILE`	Optional source file for single-file image comparison. Mutually exclusive with `--source-dir`.
`--expect-crc32 EXPECT_CRC32`	Expected cumulative data CRC32 in hex. Verification fails if the computed value differs.
`--expect-manifest-sha256 EXPECT_MANIFEST_SHA256`	Expected manifest SHA256 as 64 hex characters. Verification fails if it differs.
`--ekpfs-key EKPFS_KEY`	Optional 64-hex EKPFS key for encrypted images.
`--new-crypt`	Use the alternate `newCrypt` EKPFS derivation.

`inspect`

mkpfs inspect [-h] [--format {text,json}] [--ekpfs-key EKPFS_KEY] [--new-crypt] image_file

Examples:

mkpfs inspect ./game.ffpfs
mkpfs inspect ./game.ffpfs --format json

Parameter	Description
`image_file`	Path to the input `.ffpfs` image.
`-h`, `--help`	Show help and exit.
`--format {text,json}`	Output format for the inspection report. Default: `text`.
`--ekpfs-key EKPFS_KEY`	Optional 64-hex EKPFS key for encrypted images.
`--new-crypt`	Use the alternate `newCrypt` EKPFS derivation.

`tree`

mkpfs tree [-h] [--ekpfs-key EKPFS_KEY] [--new-crypt] image_file

Examples:

mkpfs tree ./game.ffpfs

Parameter	Description
`image_file`	Path to the input `.ffpfs` image.
`-h`, `--help`	Show help and exit.
`--ekpfs-key EKPFS_KEY`	Optional 64-hex EKPFS key for encrypted images.
`--new-crypt`	Use the alternate `newCrypt` EKPFS derivation.

`unpack`

mkpfs unpack [-h] [--overwrite] [--ekpfs-key EKPFS_KEY] [--new-crypt] image_file output_dir

Examples:

mkpfs unpack ./game.ffpfs ./extracted/
mkpfs unpack ./game.ffpfs ./extracted/ --overwrite

Parameter	Description
`image_file`	Path to the input `.ffpfs` image.
`output_dir`	Destination directory for extraction.
`-h`, `--help`	Show help and exit.
`--overwrite`	Overwrite an existing output path.
`--ekpfs-key EKPFS_KEY`	Optional 64-hex EKPFS key for encrypted images.
`--new-crypt`	Use the alternate `newCrypt` EKPFS derivation.

🔁 Typical Workflow

# 1. Pack an image from a source tree
mkpfs pack folder ./input ./output.ffpfs

# 2. Verify the generated image
mkpfs verify ./output.ffpfs

# 3. Inspect the final tree layout
mkpfs tree ./output.ffpfs

💻 Example Output

$ mkpfs pack folder --verify --compress "./BREW00000-app" "./BREW00000.ffpfs"
======================================================================
PFS Image Builder - Parameters
======================================================================
  Source path:       ./BREW00000-app
  Output path:       ./BREW00000.ffpfs
  Version:           1 (PS4)
  Header magic:      PFS (20130315)
  Compression Setup: PFSC (0x43534650)
  Block size:        65,536 bytes (64 KiB)
  Inode width:       32-bit
  PFS mode:          0x0008  (Bit 0=signed, Bit 1=64-bit inodes, Bit 2=encrypted, Bit 3=case insensitive)
    Signed:          no
    64-bit inodes:   no
    Encrypted:       no
    New crypt:       no
    Case insensitive: yes
  Compression:       enabled
  Game-file checks:   disabled
  Threshold gain:    20%
  CPU cores:         auto (max(1, cpu_count()))
  Zlib level:        7
  Dry run:           no
======================================================================

Discovering files...
[################################] 100% scan

Compressing 180 files (5.87 GB) using 10 CPU cores...
[################################] 100% compress @ 68.75 MB/s            

Writing PFS image to ./BREW00000.ffpfs...
[################################] 100% write @ 728.27 MB/s

Successfully wrote 3.21 GB image
======================================================================
Build Summary
======================================================================
  Input path:              ./BREW00000-app
  Output path:             ./BREW00000.ffpfs
  Total files:             180
  Total uncompressed size: 5.87 GB
  Total stored size:       3.21 GB

  Compression Statistics:
    Compressed files:       53
    Uncompressed files:     127
    Actual gain achieved:   45.40%
    Max theoretical gain:   46.51%  (3.14 GB if all files compressed)

  Block Alignment Waste:
    Block size:             64 KiB (65,536 bytes)
    Wasted space:           6.75 MB (0.21% of file data blocks)

  Elapsed time:            92.46s
  Throughput:              65.05 MB/s


Running post-create check...
======================================================================
PFS Check Report
======================================================================
Image:                 ./BREW00000.ffpfs
Version:               1 (PS4)
Header magic:          PFS (20130315)
Compression Setup:     PFSC (0x43534650)
Read-only:             yes
Mode:                  0x0008  (Bit 0=signed, Bit 1=64-bit inodes, Bit 2=encrypted, Bit 3=case insensitive)
  Signed:              no
  64-bit inodes:       no
  Encrypted:           no
  Case insensitive:    yes
Block size:            65,536 bytes
Inodes:                196
Directories:           14
Files:                 180
Compressed files:      53
Files hash-checked:    180
Data CRC32:            0x7A6E1B38
Manifest SHA256:       5eee3aed04394d0abf978037ccfc6ddcf9c3945fa11816fe14f11d5853e5553e
Logical file bytes:    3,443,395,982
Stored file bytes:     6,306,784,749
flat_path_table keys:  193
Warnings:              0
Errors:                0
======================================================================

🛠️ Development

Set up the local environment:

uv sync --group dev
uv run pre-commit install

Run the validation commands:

./run-tests.sh
uv run --frozen ruff format .
uv run --frozen ruff check .

💙 Special thanks and Contributors

Special thanks to the people and communities helping shape MkPFS:

Renan @ PSBrew: main creator and maintainer of MkPFS
Darkmor @ ShadowMountPlus: creator of ShadowMountPlus, whose work helped inspire practical PFS mounting workflows
The PlayStation and reverse-engineering community: for tools, research threads, testing feedback, technical notes, and historical knowledge
Community-maintained references and wiki pages: especially the projects and archives that preserve PFS, PKG, and FPKG implementation details

Related projects

ShadowMountPlus: Practical PS5 auto-mounter and a key reference for .ffpfs compatibility
PSDevWiki PFS: Community reference for PFS on-disk structures
PSDevWiki PKG files: PKG format reference and tooling pointers
ShadPKG HOWWORKS: Implementation-focused PKG/PFS decryption walkthrough
Wololo: PS4 FPKG writeup by Flatz: Historical writeup on FPKG/PKG techniques

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.claude		.claude
.github		.github
assets/images		assets/images
mkpfs		mkpfs
related-projects		related-projects
tests/mkpfs		tests/mkpfs
.codex		.codex
.editorconfig		.editorconfig
.gitignore		.gitignore
.gitmodules		.gitmodules
.openclaude		.openclaude
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
run-tests.sh		run-tests.sh
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

MkPFS

🎯 Why MkPFS

🚀 Quick Start

💖 Sponsorship

📊 Compression Statistics

📦 Installation

Run from a local checkout

Install from PyPI

Install as a local tool

Build distributables

Command Reference

Top-level CLI

`pack`

`pack folder`

`pack file`

`verify`

`inspect`

`tree`

`unpack`

🔁 Typical Workflow

💻 Example Output

🛠️ Development

💙 Special thanks and Contributors

Related projects

About

Uh oh!

Releases 2

Sponsor this project

Uh oh!

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

MkPFS

🎯 Why MkPFS

🚀 Quick Start

💖 Sponsorship

📊 Compression Statistics

📦 Installation

Run from a local checkout

Install from PyPI

Install as a local tool

Build distributables

Command Reference

Top-level CLI

pack

pack folder

pack file

verify

inspect

tree

unpack

🔁 Typical Workflow

💻 Example Output

🛠️ Development

💙 Special thanks and Contributors

Related projects

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`pack`

`pack folder`

`pack file`

`verify`

`inspect`

`tree`

`unpack`

Packages