Skip to main content

compress_json

pip python license downloads Github Actions

The missing Python utility to read and write compressed JSONs.

The library is loosely based on the compress_pickle library.

How do I install this package?

As usual, just download it using pip:

pip install compress_json

Available compression modes

The compression modes, detected automatically by the file name, are gzip, bz2, and lzma (or xz), with the notable exception of zip which seems difficult to integrate into the JSON pipeline.

Usage example

The library is extremely easy to use:

import compress_json

D = {
    "A": {
        "B": "C"
    }
}
compress_json.dump(D, "filepath.json.gz")   # for a gzip file
compress_json.dump(D, "filepath.json.bz")   # for a bz2 file
compress_json.dump(D, "filepath.json.lzma") # for a lzma file
compress_json.dump(D, "filepath.json.xz") # for a lzma file

D1 = compress_json.load("filepath.json.gz")   # for loading a gzip file
D2 = compress_json.load("filepath.json.bz")   # for loading a bz2 file
D3 = compress_json.load("filepath.json.lzma") # for loading a lzma file
D3 = compress_json.load("filepath.json.xz") # for loading a lzma file

If it happens that you have to load or dump a JSON object with a custom extension, you can specify the compression mode by passing the compression parameter to the load and dump methods:

import compress_json

D = {
    "A": {
        "B": "C"
    }
}

compress_json.dump(D, "filepath.custom_extension1", compression="gzip")   # for a gzip file
compress_json.dump(D, "filepath.custom_extension2", compression="bz2")   # for a bz2 file
compress_json.dump(D, "filepath.custom_extension3", compression="lzma") # for a lzma file

D1 = compress_json.load("filepath.custom_extension1", compression="gzip")   # for loading a gzip file
D2 = compress_json.load("filepath.custom_extension2", compression="bz2")   # for loading a bz2 file
D3 = compress_json.load("filepath.custom_extension3", compression="lzma") # for loading a lzma file

assert D == D1 == D2 == D3

Some extra perks: local loading and dumping

The library makes available, other than the usual load and dump from the JSON library, the methods local_load and local_dump, which let you load and dump files in the same directory as wherever you are calling them, by using the call stack.

This can be useful, especially when loading files within packages.

import compress_json

D = {
    "A": {
        "B": "C"
    }
}
compress_json.local_dump(D, "filepath.json.gz")   # for a gzip file
compress_json.local_dump(D, "filepath.json.bz")   # for a bz2 file
compress_json.local_dump(D, "filepath.json.lzma") # for a lzma file

D1 = compress_json.local_load("filepath.json.gz")   # for loading a gzip file
D2 = compress_json.local_load("filepath.json.bz")   # for loading a bz2 file
D3 = compress_json.local_load("filepath.json.lzma") # for loading a lzma file

assert D == D1 == D2 == D3

Loading with RAM cache

Sometimes you need to load a compressed JSON file a LOT of times, and you may want to put this document in a cache or something of the sort. Fortunately, we already provide this option for you:

import compress_json

# The first time you load the file, it will be cached in RAM
D1 = compress_json.load(
    "filepath.json.gz",
    use_cache=True
)

# The second time you load the file, it will be loaded from the cache
D2 = compress_json.local_load(
    "filepath.json.gz",
    use_cache=True
)

assert D1 == D2

Advanced usage

You can pass parameters to either the chosen compression mode or the JSON library.

With the json_kwargs parameter, you can specify any of the kwargs that should be forwarded to the JSON library method, which you can obtain for your Python version by running help(json.dump) and help(json.load), depending on whether you are dumping or loading the JSON object.

Similarly, with the compression_kwargs parameter, you can specify any parameter that has to be forwarded to the compression library that you intend to use, whether that is lzma, gzip, or bz2, and as per JSON will depend on which version you have installed.

Whether you are dumping or loading a compressed JSON object, you can get the list of parameters you have available to forward to the compression method by running help(lzma.open), help(gzip.open), or help(bz2.open), respectively.

import compress_json

D = {
    "A": {
        "B": "C"
    }
}
compress_json.dump(
    D, "filepath.json.gz",
    compression_kwargs={
        "compresslevel": 9 # The kwargs for gzip
    },
    json_kwargs={
        "indent": 4 # The kwargs for json
    }
)

D4 = compress_json.load(
    "filepath.json.gz",
    compression_kwargs={ 
        "compresslevel": 9 # The kwargs for gzip
    },
    json_kwargs={} # The kwargs for json
)

assert D == D4

Building

Run uv build to create the source distribution and wheel.

Releasing

Set a new version in compress_json/__version__.py and publish a GitHub release with a matching tag, optionally prefixed with v. The publish.yml workflow tests, builds, and publishes the source distribution and wheel through the pypi environment using PyPI Trusted Publishing.

License

The library is released under the MIT license.

Metadata

Release files for compress-json 1.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for compress-json 1.1.2
File Size Uploaded Provenance Actions
compress_json-1.1.2.tar.gz 7.8 kB With provenance Details for compress_json-1.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for compress-json 1.1.2
File Interpreter ABI Platform Actions
compress_json-1.1.2-py3-none-any.whl Python 3 none any Details for compress_json-1.1.2-py3-none-any.whl

Total release size: 14.5 kB

Release files / compress_json-1.1.2.tar.gz

Download URL compress_json-1.1.2.tar.gz
Size 7.8 kB
Tags Source
SHA-256 checksum
How to use checksums
a10c5575747c021a8957bb04e61ea74d438974a14544bcea5c46b7ff0314f492
BLAKE2b-256 checksum
How to use checksums
bb4be303682505eee71b5823807cba352691ef096db5f8bb889050967cd73eb3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / compress_json-1.1.2-py3-none-any.whl

Download URL compress_json-1.1.2-py3-none-any.whl
Size 6.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
208438e1543089ca6ff09e4430b5550657cccbf9224eeba196946187954b3492
BLAKE2b-256 checksum
How to use checksums
1a6692c380b2c4ad29996911386c1171ae71dea398fc1a11444e292224374047
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for compress-json 1.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for compress_json-1.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page