Skip to main content

NSZ - Homebrew compatible NSP/XCI compressor/decompressor

Project description

How to install:

Put dumped prod.keys to %userprofile%/.switch, install python, execute "pip install nsz" and use "nsz" like every other cmd command.

or just use the windows portable build.

To manually install dependencies use:
pip install -r requirements.txt

How to Update

pip install nsz --upgrade
or download the latest windows portable build.


NSZ files are not a real format, they are functionally identical to NSP files. Their sole purpose to alert the user that it contains compressed NCZ files. NCZ files can be mixed with NCA files in the same container.

NSC_Builder supports compressing NSP to NSZ, and decompressing NSZ to NSP. The sample scripts located here are just examples of how the format works.

NSC_Builder can be downloaded at


XCZ files are not a real format, they are functionally identical to XCI files. Their sole purpose to alert the user that it contains compressed NCZ files. NCZ files can be mixed with NCA files in the same container.


These are compressed NCA files. The NCA's are decrypted, and then compressed using zStandard. Only NCA's with a 0x4000 byte header are supported (CNMT nca's are not supported).

The first 0x4000 bytes of a NCZ file is exactly the same as the original NCA (and still encrypted).

At 0x4000, there is the variable sized NCZ Header. It contains a list of sections which tell the decompressor how to re-encrypt the NCA data after decompression. It can also contain an optional block compression header allowing random read access.

All of the information in the header can be derived from the original NCA + Ticket, however it is provided preparsed to make decompression as easy as possible for third parties.

Directly after the NCZ header, the zStandard stream begins and ends at EOF. The stream is decompressed to offset 0x4000. If block compression is used the stream is splatted into independent blocks and can be decompressed as shown in

class Section:
	def __init__(self, f):
		self.magic = # b'NCZSECTN'
		self.offset = f.readInt64()
		self.size = f.readInt64()
		self.cryptoType = f.readInt64()
		f.readInt64() # padding
		self.cryptoKey =
		self.cryptoCounter =

class Block:
	def __init__(self, f):
		self.magic = # b'NCZBLOCK'
		self.version = f.readInt8()
		self.type = f.readInt8()
		self.unused = f.readInt8()
		self.blockSizeExponent = f.readInt8()
		self.numberOfBlocks = f.readInt32()
		self.decompressedSize = f.readInt64()
		self.compressedBlockSizeList = []
		for i in range(self.numberOfBlocks):
sectionCount = nspf.readInt64()
for i in range(sectionCount):

if blockCompression:
	BlockHeader = Block(nspf)

Compressor script

Requires latest hactool compatible prod.keys at
Windows: %userprofile%.switch\ (enter .switch. as foldername to get a folder named .switch)
Linux: $HOME/.switch/
or keys.txt at the location of
Please dump your keys using
Always keep your keys up to date as otherwise newer games can't be decrypted anymore.

Example usage:
nsz --level 18 -C title1.nsp title2.nsp title3.nsp
will generate title1.nsz title2.nsz title3.nsz

This tool was only tested with base games, updates and DLCs.

Usage --help
usage: [-h] [-C] [-D] [-l LEVEL] [-B] [-s BS] [-V] [-p] [-t THREADS]
              [-o OUTPUT] [-w] [-r] [-i INFO] [--depth DEPTH]
              [-x EXTRACT [EXTRACT ...]] [-c CREATE] [--rm-source]
              [file [file ...]]

positional arguments:

optional arguments:
  -h, --help            show this help message and exit
  -C                    Compress NSP
  -D                    Decompress NSZ
  -l LEVEL, --level LEVEL
                        Compression Level
  -B, --block           Uses highly multithreaded block compression with
                        random read access allowing compressed games to be
                        played without decompression in the future however
                        this comes with a low compression ratio cost. Current
                        title installers do not support this yet.
  -s BS, --bs BS        Block Size for random read access 2^x while x between
                        14 and 32. Default is 20 => 1 MB. Current title
                        installers do not support this yet.
  -V, --verify          Verifies files after compression raising an unhandled
                        exception on hash mismatch and verify existing NSP and
                        NSZ files when given as parameter
  -p, --parseCnmt       Extract TitleId/Version from Cnmt if this information
                        cannot be obtained from the filename. Required for
                        skipping/overwriting existing files and --rm-old-
                        version to work properly if some not every file is
                        named properly. Supported filenames:
  -t THREADS, --threads THREADS
                        Number of threads to compress with. Numbers < 1
                        corresponds to the number of logical CPU cores.
  -o OUTPUT, --output OUTPUT
                        Directory to save the output NSZ files
  -w, --overwrite       Continues even if there already is a file with the
                        same name or title id inside the output directory
  -r, --rm-old-version  Removes older version if found
  -i INFO, --info INFO  Show info about title or file
  --depth DEPTH         Max depth for file info and extraction
  -x EXTRACT [EXTRACT ...], --extract EXTRACT [EXTRACT ...]
                        extract / unpack a NSP
  -c CREATE, --create CREATE
                        create / pack a NSP
  --rm-source           Deletes source file/s after compressing/decompressing.
                        It's recommended to only use this in combination with


NSZ pip package:
Forum thread:


SciresM for his hardware crypto functions; the blazing install speeds (50 MB/sec +) achieved here would not be possible without this.

Project details

Download files

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

Source Distribution

nsz-2.1.1.tar.gz (44.1 kB view hashes)

Uploaded source

Built Distribution

nsz-2.1.1-py3-none-any.whl (54.0 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page