# Core Purpose > shiv is a command-line utility for building fully self-contained Python zipapps as outlined in PEP 441, but with all their dependencies included. - Skill: `tools-only/core-purpose` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/core-purpose` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/core-purpose/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/core-purpose --- # shiv ## Overview shiv is a command-line utility for building fully self-contained Python zipapps as outlined in PEP 441, but with all their dependencies included. It is developed and maintained by LinkedIn and provides a fast, easy way to distribute Python applications. **Official Repository**: @ **Official Documentation**: @ **PyPI Package**: @ ## Core Purpose ### Problem Statement shiv solves the challenge of distributing Python applications with all their dependencies bundled into a single executable file without requiring complex build processes or compilation. **What problems does shiv solve?** 1. **Dependency bundling**: Packages your application and all its dependencies into a single `.pyz` file 2. **Simple distribution**: Creates executable files that can be shared and run on systems with compatible Python installations 3. **No compilation required**: Unlike PyInstaller or cx_Freeze, shiv does not compile Python code to binaries 4. **Fast deployment**: Built on Python's standard library zipapp module (PEP 441) for minimal overhead 5. **Reproducible builds**: Creates deterministic outputs for version control and deployment **When you would be "reinventing the wheel" without shiv:** - Building custom scripts to bundle dependencies with applications - Manually creating zipapp structures with dependencies - Writing deployment automation for Python CLI tools - Managing virtual environments on deployment targets ## When to Use shiv vs Alternatives ### Use shiv When - Deploying Python applications to controlled environments where Python is already installed - Building CLI tools for internal distribution within organizations - Creating portable Python applications for Linux/macOS/WSL environments - You need fast build times and simple deployment workflows - Your application is pure Python or has platform-specific compiled dependencies that can be installed per-platform - You want to leverage the PEP 441 zipapp standard ### Use PyInstaller/cx_Freeze When - Distributing to end-users who do not have Python installed - Creating true standalone executables with embedded Python interpreter - Targeting Windows environments without Python installations - Building GUI applications for general consumer distribution - You need absolute portability without Python runtime dependencies ### Use wheel/sdist When - Publishing libraries to PyPI - Developing packages meant to be installed via pip - Creating reusable components rather than standalone applications - Working in environments where pip/package managers are the standard ## Decision Matrix ```text ┌─────────────────────────┬──────────┬─────────────┬───────────┐ │ Requirement │ shiv │ PyInstaller │ wheel │ ├─────────────────────────┼──────────┼─────────────┼───────────┤ │ Python required │ Yes │ No │ Yes │ │ Build speed │ Fast │ Slow │ Fast │ │ Bundle size │ Small │ Large │ Smallest │ │ Cross-platform binary │ No │ Yes │ No │ │ PEP 441 compliant │ Yes │ No │ N/A │ │ Installation required │ No │ No │ Yes (pip) │ │ C extension support │ Limited* │ Full │ Full │ └─────────────────────────┴──────────┴─────────────┴───────────┘ * C extensions work but are platform-specific (not cross-compatible) ``` ## Python Version Compatibility - **Minimum Python version**: 3.8 (per setup.cfg @) - **Tested versions**: 3.8, 3.9, 3.10, 3.11 - **Python 3.11+ compatibility**: Fully compatible - **Python 3.12-3.14 status**: Expected to work (relies on standard library zipapp module) - **PEP 441 dependency**: Requires Python 3.5+ (PEP 441 introduced in Python 3.5) ### Installation ```bash # From PyPI pip install shiv # From source git clone https://github.com/linkedin/shiv.git cd shiv python3 -m pip install -e . ``` ## Core Concepts ### PEP 441 zipapp Integration shiv builds on Python's standard library `zipapp` module (PEP 441) which allows creating executable ZIP files. The key enhancement is automatic dependency installation and bundling. **How it works:** 1. Creates a temporary directory structure 2. Installs specified packages and dependencies using pip 3. Packages everything into a ZIP file 4. Adds a shebang line to make it executable 5. Extracts dependencies to `~/.shiv/` cache on first run ### Deployment Patterns **Single-file distribution:** ```bash # Build once shiv -c myapp -o myapp.pyz myapp # Distribute myapp.pyz # Users run: ./myapp.pyz ``` **Library bundling:** ```bash # Bundle multiple packages shiv -o toolkit.pyz requests click pyyaml ``` **From requirements.txt:** ```bash shiv -r requirements.txt -o app.pyz -c app ``` ## Usage Examples ### Basic Command-Line Tool Create a standalone executable of flake8: ```bash shiv -c flake8 -o ~/bin/flake8 flake8 ``` **Explanation:** - `-c flake8`: Specifies the console script entry point - `-o ~/bin/flake8`: Output file location - `flake8`: Package to install from PyPI **Running:** ```bash ~/bin/flake8 --version # Output: 3.7.8 (mccabe: 0.6.1, pycodestyle: 2.5.0, pyflakes: 2.1.1) ``` ### Interactive Python Environment Create an interactive executable with libraries: ```bash shiv -o boto.pyz boto ``` **Running:** ```bash ./boto.pyz # Opens Python REPL with boto available >>> import boto >>> boto.__version__ '2.49.0' ``` ### Real-World Example: CLI Application Distribution From @: ```bash # Build a self-contained zipapp using shiv poetry run poe build_shiv ``` This creates a `.pyz` file containing the smartmeter-datacollector application and all dependencies, distributable as a single file. ### Custom Python Interpreter Path ```bash shiv -c myapp -o myapp.pyz -p "/usr/bin/env python3" myapp ``` The `-p` flag specifies the shebang line for the executable. ### Building from Local Package ```bash # From current directory with setup.py or pyproject.toml shiv -c myapp -o myapp.pyz . ``` ### Advanced: Building shiv with shiv From @: ```bash python3 -m venv . source bin/activate pip install shiv shiv -c shiv -o shiv shiv ``` This creates a self-contained shiv executable using shiv itself, demonstrating bootstrapping capability. ## Integration Patterns ### CI/CD Pipeline Integration ```yaml # Example GitHub Actions workflow - name: Build application zipapp run: | pip install shiv shiv -c myapp -o dist/myapp.pyz myapp - name: Upload artifact uses: actions/upload-artifact@v3 with: name: myapp-zipapp path: dist/myapp.pyz ``` ### Makefile Integration From @: ```makefile zipapp: @echo "Building zipapp with shiv" shiv -c jans_cli_tui -o jans_cli_tui.pyz . ``` ### Poetry Integration In `pyproject.toml`: ```toml [tool.poe.tasks] build_shiv = "shiv -c myapp -o dist/myapp.pyz ." ``` Run with: `poetry run poe build_shiv` ## Platform-Specific Considerations ### Linux/macOS - **Shebang support**: Full support for `#!/usr/bin/env python3` - **Permissions**: Requires `chmod +x` for executable files - **Cache location**: `~/.shiv/` for dependency extraction ### Windows - **Shebang limitations**: Windows does not natively support shebangs - **Execution**: Must run as `python myapp.pyz` - **Alternative**: Use Python launcher: `py myapp.pyz` - **Cache location**: `%USERPROFILE%\.shiv\` ### Cross-Platform Gotchas **From @:** > Zipapps created with shiv are not guaranteed to be cross-compatible with other architectures. For example, a pyz file built on a Mac may only work on other Macs, likewise for RHEL, etc. This usually only applies to zipapps that have C extensions in their dependencies. If all your dependencies are pure Python, then chances are the pyz will work on other platforms. **Recommendation**: Build platform-specific executables for production deployments when using packages with C extensions. ## Cache Management shiv extracts dependencies to `~/.shiv/` (or `SHIV_ROOT`) on first run. This directory can grow over time. **Cleanup:** ```bash # Remove all cached extractions rm -rf ~/.shiv/ # Set custom cache location export SHIV_ROOT=/tmp/shiv_cache ./myapp.pyz ``` ## When NOT to Use shiv ### Scenarios Where Alternatives Are Better 1. **Windows-only distribution without Python**: Use PyInstaller or cx_Freeze for embedded interpreter 2. **End-user applications**: Users expect double-click executables, not Python scripts 3. **Cross-platform binaries from single build**: shiv requires platform-specific builds for C extensions 4. **Library distribution**: Use wheel/sdist and publish to PyPI 5. **Complex GUI applications**: PyInstaller has better support for frameworks like PyQt/Tkinter 6. **Environments without Python**: shiv requires a compatible Python installation on the target system ## Common Use Cases ### Internal Tool Distribution **Example**: DevOps teams distributing CLI tools ```bash # Build deployment tool shiv -c deploy -o deploy.pyz deploy-tool # Distribute to team members # Everyone runs: ./deploy.pyz --environment prod ``` ### Lambda/Cloud Function Packaging While AWS Lambda has native Python support, shiv can simplify dependency management: ```bash shiv -o lambda_function.pyz --no-binary :all: boto3 requests ``` ### Portable Development Environments Create portable toolchains: ```bash # Bundle linting tools shiv -o lint.pyz black pylint mypy flake8 # Bundle testing tools shiv -o test.pyz pytest pytest-cov hypothesis ``` ## Real-World Projects Using shiv Based on GitHub search results (@): 1. **JanssenProject/jans** - IAM authentication server - Uses shiv to build CLI and TUI applications - Makefile integration for zipapp builds - @ 2. **scs/smartmeter-datacollector** - Smart meter data collection - Poetry integration with custom build command - Self-contained distribution for Raspberry Pi - @ 3. **praetorian-inc/noseyparker-explorer** - Security scanning results explorer - TUI application distributed via shiv - @ 4. **ClericPy/zipapps** - Alternative zipapp builder - Built as comparison/alternative to shiv - @ ## Additional Resources ### Official Documentation - PEP 441 - Improving Python ZIP Application Support: @ - Python zipapp module: @ - shiv documentation: @ - Lincoln Loop blog: "Dissecting a Python Zipapp Built with Shiv": @ ### Community Resources - Real Python tutorial: "Python's zipapp: Build Executable Zip Applications": @ - jhermann blog: "Bundling Python Dependencies in a ZIP Archive": @ ### Comparison Articles - PyOxidizer comparisons (includes shiv): @ - Hacker News discussion: @ ## Technical Implementation Details ### Dependencies From @: ```ini [options] install_requires = click>=6.7,!=7.0 pip>=9.0.3 setuptools python_requires = >=3.8 ``` shiv has minimal dependencies, relying primarily on standard library components plus click for CLI and pip for dependency resolution. ### Entry Points shiv provides two console scripts: 1. `shiv`: Main build tool 2. `shiv-info`: Inspect zipapp metadata ### Build Backend Uses setuptools with pyproject.toml (PEP 517/518 compliant): ```toml [build-system] requires = ["setuptools", "wheel"] build-backend = "setuptools.build_meta" ``` ## Maintenance and Support - **License**: BSD 2-Clause License - **Maintainer**: LinkedIn (@) - **GitHub Stars**: 1,884+ (as of October 2025) - **Active Development**: Yes (last updated October 2025) - **Open Issues**: 66 (as of October 2025) - **Community**: Active issue tracker and pull request reviews ## Security Considerations 1. **Code signing**: shiv does not sign executables; implement external signing if required 2. **Dependency verification**: shiv uses pip, which respects pip's security model 3. **Cache security**: `~/.shiv/` directory contains extracted dependencies; ensure proper permissions 4. **Supply chain**: Verify package sources before building zipapps ## Performance Characteristics - **Build time**: Fast (seconds for typical applications) - **Startup overhead**: First run extracts to cache (one-time cost), subsequent runs are instant - **Runtime performance**: Native Python performance (no interpretation overhead) - **File size**: Smaller than PyInstaller bundles (no embedded interpreter) ## Troubleshooting ### Common Issues **Issue**: "shiv requires Python >= 3.8" **Solution**: Upgrade Python or use an older shiv version **Issue**: "ImportError on different platform" **Solution**: Rebuild zipapp on target platform for C extension dependencies **Issue**: "Permission denied" **Solution**: `chmod +x myapp.pyz` **Issue**: "SHIV_ROOT fills up disk" **Solution**: Clean cache: `rm -rf ~/.shiv/` or set `SHIV_ROOT` to tmpfs ## Conclusion shiv is an excellent choice for distributing Python applications in controlled environments where Python is available. It provides a simple, fast, and standards-based approach to application packaging without the complexity of binary compilation. For internal tools, CLI utilities, and cloud function packaging, shiv offers an ideal balance of simplicity and functionality. **Quick decision guide:** - Need standalone binary with no Python? Use PyInstaller/cx_Freeze - Distributing library? Use wheel + PyPI - Internal tool with Python available? Use shiv - Cross-platform GUI app? Use PyInstaller - Cloud function deployment? Consider shiv or native platform tools