{"id":9303,"library":"shiv","title":"Shiv: Python Zipapp Builder","description":"Shiv is a command-line utility for building fully self-contained Python zipapps (.pyz files) in compliance with PEP 441. It packages a Python application, its dependencies, and a Python interpreter bootstrap into a single executable file. The current version is 1.0.8, with a release cadence of relatively frequent minor releases.","status":"active","version":"1.0.8","language":"en","source_language":"en","source_url":"https://github.com/linkedin/shiv","tags":["packaging","zipapp","cli","deployment","executable"],"install":[{"cmd":"pip install shiv","lang":"bash","label":"Install Shiv"}],"dependencies":[],"imports":[],"quickstart":{"code":"import subprocess\nimport sys\nimport os\n\n# 1. Create a simple Python script to be packaged\nscript_content = \"\"\"\n# hello_app.py\nimport sys\ndef main():\n    print(f\"Hello from shiv zipapp! Python version: {sys.version.split()[0]}\")\n\nif __name__ == '__main__':\n    main()\n\"\"\"\nwith open(\"hello_app.py\", \"w\") as f:\n    f.write(script_content)\n\n# 2. Build the zipapp using shiv (assuming shiv is installed)\nprint(\"Building hello_app.pyz...\")\ntry:\n    subprocess.run(\n        [sys.executable, \"-m\", \"shiv\", \"-o\", \"hello_app.pyz\", \"-e\", \"hello_app:main\", \".\"],\n        check=True,\n        capture_output=True,\n        text=True\n    )\n    print(\"Zipapp built successfully.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error building zipapp: {e.stderr}\")\n    sys.exit(1)\n\n# 3. Execute the built zipapp\nprint(\"Executing hello_app.pyz...\")\ntry:\n    result = subprocess.run(\n        [sys.executable, \"hello_app.pyz\"],\n        check=True,\n        capture_output=True,\n        text=True\n    )\n    print(\"Zipapp output:\")\n    print(result.stdout.strip())\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error executing zipapp: {e.stderr}\")\n    sys.exit(1)\nfinally:\n    # 4. Clean up generated files\n    if os.path.exists(\"hello_app.py\"):\n        os.remove(\"hello_app.py\")\n    if os.path.exists(\"hello_app.pyz\"):\n        os.remove(\"hello_app.pyz\")\n    print(\"Cleanup complete.\")","lang":"python","description":"This quickstart demonstrates how to create a simple Python script, package it into a self-contained zipapp using `shiv`, and then execute the resulting zipapp."},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or newer when using Shiv 1.0.4+.","message":"Shiv versions 1.0.4 and newer officially drop support for Python 3.6 and 3.7. While `requires_python` might still state `>=3.6` on PyPI, testing and full compatibility are only maintained for Python 3.8 and above.","severity":"breaking","affected_versions":">=1.0.4"},{"fix":"Ensure the `.pyz` file is executable using `chmod +x my_app.pyz`.","message":"When trying to execute a `shiv` built `.pyz` file directly (e.g., `./my_app.pyz`), you may encounter 'Permission denied' errors if the file does not have execute permissions.","severity":"gotcha","affected_versions":"all"},{"fix":"Verify the module path and function name. For example, if `main` is in `my_script.py` (root of the zipapp), use `-e my_script:main`. If it's in `my_package/module.py`, use `-e my_package.module:main`.","message":"The `-e` or `--entry-point` argument must correctly specify a callable in the format `module:function`. A common mistake is providing an incorrect module path or function name, leading to `AttributeError` or `ModuleNotFoundError` at runtime.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure you are using standard Python packaging practices for resource handling if you have custom build steps. Most users will not be affected.","message":"Shiv 1.0.5 replaced deprecated `importlib.resources.*` calls internally. While this primarily affects Shiv's internal workings, users with highly customized `shiv` environments or those relying on older internal resource handling might see minor behavior changes.","severity":"deprecated","affected_versions":">=1.0.5"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `chmod +x my_app.pyz` before attempting to execute it.","cause":"The generated zipapp file does not have execute permissions.","error":"bash: ./my_app.pyz: Permission denied"},{"fix":"Ensure all required packages are listed in a `requirements.txt` file and passed with `-r requirements.txt`, or include local directories using the `.` argument if they contain your code. Check for `-S` (`--no-site-packages`) if you expect installed packages to be present.","cause":"A required dependency or a local module was not included in the zipapp, or the Python path inside the zipapp is misconfigured.","error":"Error: No such file or directory: '...' (or similar ModuleNotFoundError from within the zipapp)"},{"fix":"Double-check the entry point string. Ensure the module exists and the function name is spelled correctly and is accessible from the module. For instance, if `main` is inside a class, you might need `module:ClassName.main_method`.","cause":"The entry point specified with `-e` (e.g., `my_script:main`) does not correctly point to a callable function within the packaged application.","error":"AttributeError: module 'my_script' has no attribute 'main'"}]}