{
  "id": "jonnor/micropython-zipfile",
  "name": "micropython-zipfile",
  "prettyName": "micropython-zipfile",
  "description": "zipfile module ported from CPython to MicroPython",
  "version": "",
  "author": "jonnor",
  "license": "",
  "tags": [],
  "status": "VALID",
  "official": false,
  "source": "https://github.com/jonnor/micropython-zipfile",
  "updatedAt": "2025-06-28T07:00:19.700Z",
  "page": "https://checkmim.com/packages/jonnor+micropython-zipfile",
  "createdAt": "2025-05-27T04:28:03.397Z",
  "submittedBy": "oliverr",
  "install": {
    "mpremote": "mpremote mip install github:jonnor/micropython-zipfile",
    "mip": "import mip; mip.install(\"github:jonnor/micropython-zipfile\")"
  },
  "readme": "\n[![Tests](https://github.com/jonnor/micropython-zipfile/actions/workflows/tests.yaml/badge.svg?branch=master)](https://github.com/jonnor/micropython-zipfile/actions/workflows/tests.yaml)\n\n# micropython-zipfile\n\nSupport for [.zip files](https://en.wikipedia.org/wiki/ZIP_(file_format)) for [MicroPython](https://micropython.org/).\nPort of CPython [zipfile](https://docs.python.org/3/library/zipfile.html).\n\nA subset of .zip was standardized in ISO/IEC 21320–1:2015 \"Document Container File: Core\".\nSuch files should work with this module.\nZIP archives are used as a basis for many common files, such as EPUB, DOCX.\n\nmicropython-zipfile was initially made for [micropython-npyfile](https://github.com/jonnor/micropython-npyfile/), to support Numpy .npz files (uses a ZIP archive).\nWhich again was made for [emlearn-micropython](https://github.com/emlearn/emlearn-micropython),\na Machine Learning and Digital Signal Processing library for MicroPython.\n\n## Status\n**Minimally useful**.\n\n- Supports read/write of ZIP archives, with or without compression\n- Highly compatible with the CPython API\n- Passes over 100 tests from the CPython test suite\n- Tested on the Unix port and ESP32 port, running MicroPython 1.23\n\n## License\n\nThe majority of the code is copied from the CPython 3.12 implementation of `zipfile`.\nThat code is, to the best of our understanding, under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2.\nAll modifications/adaptations done in this project can be used under the same license.\n\n## Features\n\nThis is an adapted implementation of the original [zipfile module](https://docs.python.org/3/library/zipfile.html) in CPython.\nWith the exception of the **Limitations** documented below, it should have the same features.\n\n#### Prerequisites\n\nThis library uses the MicroPython [deflate module](https://docs.micropython.org/en/latest/library/deflate.html#deflate.DeflateIO) to handle compression and decompression.\nTherefore your MicroPython firmware build must include this module,\nwhich may require you to enable the `MICROPY_PY_DEFLATE` and `MICROPY_PY_DEFLATE_COMPRESS` features.\n\nIf you get the error `AttributeError: 'DeflateIO' object has no attribute 'write'`, you are missing `MICROPY_PY_DEFLATE_COMPRESS`.\n\n#### Limitations\n\nThese limitations could be lifted if people contribute\n\n- Only DEFLATE and STORED (uncompressed) is supported.\n- LZMA compression *not supported*\n- BZ2 compression *not supported*\n- `PathLike` objects not supported.\n- `readline()` and `readlines()` on file objects not supported\n\nThese limitations are likely to be forever.\nThis is because they are not that relevant in a microcontroller/embedded setting.\n\n- PyFile objects not supported\n- Usage as a command-line module not supported\n- *append* mode (`'a'` option to ZipFile) not supported.\n- *exclusive* mode (`'x'` option to ZipFile) not supported.\n- Only `ascii` and `utf-8` supported for metadata encoding\n\n## Installing\n\nThis package can be installed using [mip](https://docs.micropython.org/en/latest/reference/packages.html#installing-packages-with-mip).\n\nFor example:\n\n```bash\nmpremote mip install github:jonnor/micropython-zipfile\n```\n\nOr just copy the `zipfile.py` file to your MicroPython device.\n\n## Usage\n\n#### Create a ZIP archive\n\n```python\n# Import the module\nfrom zipfile import ZipFile, ZIP_DEFLATED, ZIP_STORED\n\n# Create a .zip archive\n# for compression, swap ZIP_STORED with ZIP_DEFLATED\npath = 'myarchive.zip'\nwith ZipFile(path, 'w', ZIP_STORED) as archive: \n    contents = b'Hello World Hello World Hello World\\n'\n    with archive.open('test.txt', 'w') as f:\n        f.write(contents)\n```\n\n#### List what is inside a ZIP archive\n```python\n# List the information from a .zip archive\nprint('\\nListing information')\nwith ZipFile(path, 'r') as archive: \n    for info in archive.infolist(): \n        print(info.filename)\n        print('\\tSystem:\\t\\t' + str(info.create_system) + '(0 = Windows, 3 = Unix)') \n        print('\\tZIP version:\\t' + str(info.create_version)) \n        print('\\tCompressed:\\t' + str(info.compress_size) + ' bytes') \n        print('\\tUncompressed:\\t' + str(info.file_size) + ' bytes') \n```\n\n#### Read data from a file inside ZIP archive\n\n```python\n# Read a file from inside .zip archive\nprint('\\nReading file')\nwith ZipFile(path) as myzip:\n    with myzip.open('test.txt') as myfile:\n        print(myfile.read())\n```\n\n#### More\n\nAlso see [examples](./examples).\nAnd consult tutorials and the API reference for the CPython zipfile module.\n\n## TODO \nContributions welcomed!\n\n## Other implementations\n\n- [maruno/mpy-blox zipfile.py](https://github.com/maruno/mpy-blox/blob/master/mpy_blox/zipfile.py). Minimal implementation of `zipfile.ZipFile` which supports only reading. The function `read()` supports uncompressed or deflate compressed data.\nNot clear if ZIP64 is supported. Not separately installable.\n\n## Developing\n\n#### Running tests on host\n\nInstall the Unix/Windows port of MicroPython.\n\nInstall modules used by the tests\n\n```\nmicropython -m mip install contextlib unittest os-path stat shutil\n```\n\nRun the basic test suite:\n\n```\nMICROPYPATH=.:$HOME/.micropython/lib micropython tests/test_zipfile.py\n```\n\nRun the full test suite with MicroPython:\n\n```\nMICROPYPATH=.:$HOME/.micropython/lib micropython -X heapsize=10M test_zipfile/test_core.py\n```\n\nThe tests can also be ran under CPython\n```\nPYTHONPATH=./ python test_zipfile/test_core.py  -v\nMICROPYPATH=.:$HOME/.micropython/lib micropython tests/test_zipfile.py\n```\n\n#### Running tests on device\n\nConnect a MicroPython device via USB.\n\nCopy over the data\n```\nmpremote cp zipfile.py :\nmpremote run tests/test_zipfile.py\n```\n\n"
}