{"id":9421,"library":"zip-files","title":"zip-files","description":"The `zip-files` Python library provides command-line utilities, `zip-files` and `zip-folder`, for creating ZIP archives. It offers an easy, platform-independent way to compress files and folders, allowing control over the internal root folder structure and compression method. The current version is 0.4.1, and its release cadence has been infrequent, with the last update in April 2021.","status":"active","version":"0.4.1","language":"en","source_language":"en","source_url":"https://github.com/goerz/zip_files","tags":["zip","archive","compression","cli","utility","files"],"install":[{"cmd":"pip install zip-files","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary programmatic interface is `create_zip_file` within `zip_files.api`. The top-level `zip_files` import is for CLI execution.","wrong":"import zip_files","symbol":"create_zip_file","correct":"from zip_files.api import create_zip_file"},{"note":"The `zip-files` library builds on Python's standard `zipfile` module. Direct usage of `ZipFile` for advanced operations should be from the standard library.","wrong":"from zip_files.api import ZipFile","symbol":"ZipFile","correct":"import zipfile"}],"quickstart":{"code":"import os\nfrom zip_files.api import create_zip_file\n\n# Create some dummy files for zipping\nwith open('file1.txt', 'w') as f:\n    f.write('Content of file 1')\nwith open('file2.py', 'w') as f:\n    f.write('print(\"Hello from file 2\")')\n\noutput_zip = 'my_archive.zip'\nfiles_to_zip = ['file1.txt', 'file2.py']\nroot_folder_in_zip = 'my_data'\n\nprint(f\"Creating {output_zip} with files in root folder '{root_folder_in_zip}'...\")\ncreate_zip_file(output_zip, files_to_zip, root_folder=root_folder_in_zip)\nprint(f\"Successfully created {output_zip}\")\n\n# You can also use the command-line utility\n# import subprocess\n# subprocess.run(['zip-files', '-f', 'another_data', 'another_archive.zip', 'file1.txt', 'file2.py'])\n\n# Cleanup (optional)\nos.remove('file1.txt')\nos.remove('file2.py')\nos.remove(output_zip)\n","lang":"python","description":"This quickstart demonstrates how to use the `create_zip_file` function from the programmatic API to generate a ZIP file. It includes creating two dummy files, zipping them into `my_archive.zip` under a specified root folder, and then cleaning up the generated files. The library also provides command-line tools `zip-files` and `zip-folder`."},"warnings":[{"fix":"Ensure you are importing from `zip_files.api` if you intend to use the programmatic interface of this specific library, or `import zipfile` for the standard library functionality.","message":"The `zip-files` package (hyphenated PyPI name) provides CLI utilities and a thin Python API, but it is distinct from Python's built-in `zipfile` module (underscore name). Many online resources refer to the standard `zipfile` module, which offers a more comprehensive API for ZIP archive manipulation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always validate the integrity of downloaded ZIP files. If encountering issues, try re-downloading the file or using an alternative extraction tool. For programmatic handling, wrap `zipfile.ZipFile` operations in `try-except BadZipFile` blocks. Ensure the correct compression method is specified when creating archives if compatibility is an issue.","message":"ZIP files, especially large or corrupted ones, can be prone to extraction errors such as `BadZipFile` or `BadZipfile` (deprecated alias). This can be caused by incomplete downloads, header corruption, or unsupported compression methods if the archive was created by another tool.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully consider the desired structure of the extracted ZIP. Use `-f` or `--root-folder` in the CLI, or the `root_folder` argument in `create_zip_file`, to control the top-level directory.","message":"When creating ZIP files, be mindful of the `root_folder` parameter. If not specified, files are added directly to the archive's root. If a `root_folder` is provided, all included files and folders will reside within that single top-level directory upon extraction. This influences how users interact with the extracted content.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed in an environment whose `Scripts` directory is in your PATH. If using `pipx`, ensure the virtual environment is correctly linked. Reinstall using `pip install zip-files`.","cause":"The `zip-files` command-line utility is not in your system's PATH, or the package was not installed correctly.","error":"command not found: zip-files"},{"fix":"Verify the file's integrity and ensure it is a complete, valid ZIP archive. Try opening it with a standard unzipping tool. If using the Python API, check the path and permissions.","cause":"Attempting to open a file that is either not a valid ZIP archive or is corrupted, possibly due to an incomplete download or incorrect file extension.","error":"zipfile.BadZipFile: File is not a zip file"},{"fix":"Attempt to re-compress the archive using a widely supported method like 'deflated' (default for `zip-files`). If reading, use a tool that supports the specific compression method, or consider libraries like `zipfile-deflate64` or `zipfile-inflate64` if `DEFLATE64` is the issue.","cause":"The ZIP file was created using a compression method (e.g., Deflate64, old proprietary methods) that is not supported by Python's standard `zipfile` module (which `zip-files` relies upon) or the specific `compression` argument used.","error":"zipfile.BadZipFile: Unsupported compression method"}]}