Intermediate

Sharing a Python script with a colleague is easy until it has dependencies. Suddenly you need to say “first install Python, then create a virtual environment, then pip install these five packages, then run the script.” Half the time something breaks on their machine because they are on a different OS version, have conflicting packages, or simply misread one of the steps. You end up spending more time on setup instructions than on the actual tool you built.

Python’s built-in zipapp module solves the distribution problem for CLI tools and internal utilities. It bundles your application code — and optionally its dependencies — into a single .pyz file that runs with python myapp.pyz on any machine that has Python installed. No virtual environment, no pip install, no path configuration. One file, one command.

In this article you will learn how to create a basic zipapp from the command line, bundle dependencies into the archive, set a custom entry point, add a shebang line for Unix direct execution, work around the limitations of compiled extensions, and finish with a real-life example: packaging a CSV-to-JSON converter as a portable .pyz file. By the end you will be distributing Python tools as single files the way Go developers take for granted.

zipapp Quick Example

Here is the minimal workflow — a Python script bundled into a .pyz archive that runs on any machine with Python 3:

# Step 1: create the source directory
# myapp/
#   __main__.py
#   utils.py

# myapp/__main__.py
def main():
    from myapp.utils import greet
    greet("World")

if __name__ == "__main__":
    main()
# myapp/utils.py
def greet(name: str) -> None:
    print(f"Hello, {name}! Running from a .pyz archive.")
# quick_build.py -- run this once to create the archive
import zipapp
zipapp.create_archive("myapp", target="myapp.pyz", interpreter="/usr/bin/env python3")
print("Created myapp.pyz")

Then run it:

$ python myapp.pyz
Hello, World! Running from a .pyz archive.

The .pyz file is a ZIP archive with a Python shebang prepended. Python’s import system knows how to find modules inside ZIP archives (PEP 302), so all imports work exactly as if the files were on disk. The __main__.py file is the entry point that runs when you execute the archive.

What Is zipapp and When Should You Use It?

A Python zip application (.pyz) is a ZIP file that starts with a shebang line (#!/usr/bin/env python3) and contains a __main__.py as its entry point. Python has supported executing ZIP archives since Python 2.6 (PEP 441). The zipapp module, added in Python 3.5, automates the creation process so you do not have to build the ZIP manually.

Distribution methodSingle fileDependencies bundledPython requiredCross-platform
zipapp (.pyz)YesYes (pure Python)YesYes
PyInstallerYesYes (incl. C extensions)NoNo (per-OS build)
pip packageNoVia dependenciesYesYes
Docker imageNoYes (everything)NoPartial

zipapp is the right choice for internal tools, CI scripts, and developer utilities where you know the target machine has Python and you want to share one file over Slack or email. It is not suitable for end-user consumer apps (use PyInstaller or packaging) or for tools that require C extension dependencies (use Docker).

Creating Archives from the Command Line

The zipapp module has a command-line interface that handles the most common cases without writing any Python:

# Command-line usage (run in your terminal, not Python)

# Basic: package a directory into a .pyz
$ python -m zipapp myapp -o myapp.pyz

# With a custom entry point (module:callable syntax)
$ python -m zipapp myapp -o myapp.pyz -m "myapp.cli:main"

# With a shebang for direct Unix execution (chmod +x myapp.pyz first)
$ python -m zipapp myapp -o myapp.pyz -p "/usr/bin/env python3" -m "myapp.cli:main"

# Inspect an existing archive's entry point
$ python -m zipapp --info myapp.pyz
Interpreter: /usr/bin/env python3
Main: myapp.cli:main

The -m "module:callable" flag writes a __main__.py shim that imports and calls the specified function. This means you do not need to write a __main__.py yourself — zipapp generates it. The generated __main__.py looks like:

# Generated __main__.py (created by -m flag)
import sys
sys.exit(__import__("myapp.cli").cli.main())

This is exactly what you would write manually, but you get it for free by specifying the entry point flag.

Bundling Dependencies into the Archive

To bundle third-party pure-Python packages, install them into a subdirectory, then include that directory when building the archive. The key is that everything inside the archive ZIP is available on the import path when the archive runs:

# build_with_deps.py
import subprocess
import zipapp
import shutil
import os

APP_DIR = "myapp_with_deps"
BUILD_DIR = "build_temp"

# Clean build dir
shutil.rmtree(BUILD_DIR, ignore_errors=True)
os.makedirs(BUILD_DIR)

# Copy application source
shutil.copytree(APP_DIR, os.path.join(BUILD_DIR, "myapp_with_deps"))

# Install pure-Python dependencies directly into the build dir	�Չ�ɽ���̹�ո�l(���������������х����(�������хɝ�Ј��	U%1}%H����������х�����Ѽ��ե�����Ȱ���Ёͥє���������(��������������������������������ͭ�����匁�������ѥ������Ё�����������ɍ��ٔ�(�������������ĸ܈���������������ᅵ����
1$��Ʌ��ݽɬ(�����ɕ�Օ�����ȸ�ĸ�������������ᅵ����!QQ@����Ʌ��)t��������Q�Ք�((��I���ٔ���䀹���е�������ɕ�ѽɥ�̀���Ё��������Ё�չѥ���)��ȁ�ѕ������̹���ё�ȡ	U%1}%H��(��������ѕ������ݥѠ������е��������ȁ�ѕ������ݥѠ��������������(��������͡�ѥ��ɵ�ɕ���̹��Ѡ������	U%1}%H���ѕ���((��	ե���ѡ���ɍ��ٔ)�������ɕ�ѕ}�ɍ��ٔ�(����	U%1}%H�(����хɝ������}ݥѡ}���̹��舰(������ѕ��ɕѕ����Ƚ������؁��ѡ��̈�(������������}ݥѡ}���̹���鵅����(��������ɕ�͕��Q�Ք������������ɕ�́���ɥ�́Ѽ�ɕ�Ս�������ͥ�(�()�ɥ�С��	ե�Ё����}ݥѡ}���̹��耡��̹��Ѡ����ͥ锠�����}ݥѡ}���̹��蜤���������-���(𽍽�����ɔ�((������ɽ���=���������ɽ������(��ɔ�񍽑��	ե�Ё����}ݥѡ}���̹��耠��܁-�(𽍽�����ɔ�((���Q���񍽑����хɝ�Ё	U%1}%H𽍽���������ѕ��́����Ѽ����х����������́��Ѽ���ȁ�ե�����ɕ�ѽ�䁥��ѕ������ѡ�����ѕ��ͥє��������̸�Q���񍽑��������������𽍽���������ͭ��̀񍽑�����𽍽��������Ʌѥ���ͥ����ѡ���ɍ��ٔ�ݥ������������������Ё�����Ё���݅丁I���٥���񍽑������е����𽍽������ɕ�ѽɥ�́�́��ѥ�������Ё����́ѡ���ɍ��ٔ�͵����ȸ�M�Ѐ񍽑������ɕ�͕��Q�Ք𽍽����Ѽ��������i%@�����ɕ�ͥ��������ȁ��ɔ�A�ѡ��������ѡ�́���������ɕ�Ս�́ͥ锁������������((�����%5}A1
!=1H�
�����-�ѥ��ݥѠ���͍�����ݕ�����������ɝ�������������������䁙���́������Ё��ͥ�����������Ё�ɍ��ٔ��Ɉ�����ɽ٥���ѡ������ɕ�ͥ����
��ѥ��耉�������х�����хɝ�Ѐ������������-����ѕ�����������͔�͕Ё�����ٕ�؁����М������((�ȁ��􉱥��хѥ��̈�1���хѥ����]��Ё������
����Ё	չ������((�����������́�����չ�����х������хѥ��聥Ё�����Ё�չ����������������ѕ�ͥ��̀�񍽑���ͼ𽍽�����Ȁ񍽑�����𽍽��������̤��A�ѡ���́�����Ё���ѕ�����������Ё��ɔ�A�ѡ�������́�ɽ����ͥ�����i%@����Ё�Ё�����Ё�����͡�ɕ�����Ʌɥ�́��ɕ�ѱ䁙ɽ����i%@��Q��́����́�������́�����񍽑���յ��𽍽�����񍽑��������𽍽�����񍽑��A�����𽍽������ȁ�����������ݥѠ�
�ѡ����ȁ����������́ݥ�����Ёݽɬ���ͥ��������������((��ɔ�񍽑���������}��ɕ}��ѡ�����(��	���ɔ��ե�������ٕɥ�䁅��������������́�ɔ���ɔ�A�ѡ��)�����Ё������)�����Ё��()�������}������}��ѕ�ͥ��̡��Ѡ���Ȥ��������m���t�(�������I���ɸ������Ё��������������ѕ�ͥ�������́��չ��չ��ȁ��Ѡ����(��������ɥ�̀�mt(������ȁɽ�а�|������́����̹݅�����Ѡ��(����������ȁ�����������(���������������������ݥѠ����ͼ������合�����������(��������������������ɥ�̹��������̹��Ѡ������ɽ�а����(����ɕ��ɸ�����ɥ��()��չ��􁡅�}������}��ѕ�ͥ��̠��ե��}ѕ����)�����չ��(�����ɥ�Р�]I9%9聉����䁕�ѕ�ͥ��́��չ�����ѡ�͔�ݥ���9=P�ݽɬ�����������舤(������ȁ�������չ��(���������ɥ�С������)��͔�(�����ɥ�Р��������Ȁ�����������䁕�ѕ�ͥ��̰�ͅ���Ѽ��չ�����́��������(𽍽�����ɔ�((���%����ȁѽ�������́�������́ݥѠ����ѕ�ͥ��̰����ͥ��ȁA�%��х���Ȁ��ɕ�ѕ́���х���������ᕍ�х������ȁ=L����ȁ����ɥ��є�������ȁ��������ȁ�ɽ٥��������������������Ё�͕�́���х���ѡ��͕�̸ٕ�����������A�%��х���ȁ�ɔ���Ё�����ѥ���ѽ��̀���ѡ��ͽ�ٔ������ɕ�Ё�ɽ����̸���((�ȁ���ɕ���������ᅵ�����I����1����ᅵ����A��х����
MX�Ѽ�)M=8�
��ٕ�ѕ����((���!�ɔ��́��������є������ɥ��х����
MX�Ѽ�)M=8����ٕ�ѕȁ����������́��ͥ�����񍽑������𽍽����������Q���ѽ����͕́����ѡ���х���ɐ����Ʌ�䰁ͼ�������������䁉չ�������́����������((��ɔ�񍽑�������ѽ�ͽ��}}����}|���(���)���ѽ�ͽ����耴�����х����
MX�Ѽ�)M=8����ٕ�ѕ�)Z\�Y�N�]ۈ�ݝڜ�ۋ�^�[�]��݈��]]���ۗB�]ۈ�ݝڜ�ۋ�^�KZ[�����[\ܝ�\š[\ܝ�݂�[\ܝ��ۂ�[\ܝ\��\��B����H]X�[\ܝ]���Y��ݗ��ڜ�ۊ[�]�]�]�]]�]�][�[��[�H�HO�[�������۝�\��Ո���ӈ\��^K��]\��������[�������][�]�]��[��]�[�OH��[���[��H�]�N�H\�����XY\�H�݋�X��XY\��B�����H\�
�XY\�B���]�]]�]��[��ȋ[���[��H�]�N�H\������ۋ�[\
�����[�[�Z[�[�[��\�W�\��ZOQ�[�JB���]\��[�����B���Y�XZ[�
N��\��\�H\��\��K�\��[Y[�\��\��\�ܚ\[ۏH��۝�\��Ո�[\����ӈ�ܛX]���
B�\��\��Y�\��[Y[�
�[�]�\OT][H�[�]�Ո�[H]�B�\��\��Y�\��[Y[�
���]]�\OT]�\���H�ȋ[H��]]��ӈ�[H
Y�][�[�]���ۊH��
B�\��\��Y�\��[Y[�
��KZ[�[��\OZ[�Y�][L��[H���ӈ[�[�][ۈ�X�\�
Y�][��\�H�܈Z[�Y�YY
H��
B�\��\��Y�\��[Y[�
�K]�\��[ۈ�X�[ۏH��\��[ۈ��\��[ۏH��ݝڜ�ۈK���B�\���H\��\��\��W�\���
B��[�]�]H\��˚[�]�Y���[�]�]�^\��
N���[�
��\��܎��[H����[���[�]�]H��[O\�\˜�\��B��\˙^]
JB���]]�]H\��˛�]]܈[�]�]��]��Y��^
����ۈ�B����[�H�ݗ��ڜ�ۊ[�]�]�]]�]\��˚[�[�
B��[�
���۝�\�Y���[�H�������H�[�]�]��[Y_H���]]�]H�B���Y��ۘ[YW��OH���XZ[��Ȏ��XZ[�
B����O���O����O���O���Z[��ݝڜ�ۋ�HKH�[�ۘ�H�ܙX]HH�^�\��]�B�[\ܝ�\\��\\�ܙX]W�\��]�J���ݝڜ�ۈ��\��]H��ݝڜ�ۋ�^���[�\��]\�H��\܋ؚ[��[��]یȋ���\�\��YU�YK�B��[�
�ܙX]Y�ݝڜ�ۋ�^��B����O���O������ۙϕ\�Y�HY�\��Z[[�Ώ���ۙϏ����O���O��ܙX]HH�[\H�Ղ�X����[YK��ܙKܘYW�[X�KMKW��؋����\��
��Ȉ��Y[�˘�݂����۝�\�]�]ۈ�ݝڜ�ۋ�^��Y[�˘�݂��۝�\�Y��������H�Y[�˘�݈��Y[�˚��ۂ����YHH�]]��]�Y[�˚��ۂ�ˆț�[YH���[X�H����ܙH���MH��ܘYH���H�K�ț�[YH����؈����ܙH������ܘYH�����K�ț�[YH����\������ܙH����ȋ�ܘYH���ȟB�B���\�X�^X�][ۈۈ[�^
Y�\��[�
�
B��[�
��ݝڜ�ۋ�^�����ݝڜ�ۋ�^��Y[�˘�݈�]]���ۈKZ[�[���۝�\�Y��������H�Y[�˘�݈��]]���ۂ����O���O��������O��ݝڜ�ۋ�^����O�[��H�\�Y�]�K[XZ[]�H��XY�YK܈��[Z]]�H�\��]ܞK�ۈ[�HXX�[�H�]]ۈ�H�[��H��[X[���O�]ۈ�ݝڜ�ۋ�^�[�]��ݏ���O��ܚ���]���]\��YH�]��X]\�KY]H��\��K�[���O��Z[��ݝڜ�ۋ�O���O�[��\�HH�]���O��^����O��H\]H�X�H\�\��[\H\��\�[��H�ܚ\�����KKHSPQ�W�P�R�T��TH[^\[H[�[��H�X[���[��ܘ�X�[Y�]H]ۈ����[��\��Y�\�K���Z[[���[\H�X[��X��ܛ�[���\[ێ���\�HH�^��^H�[�]ۈ^X\�^��[�H�]�\�]�H�^Z[�\[��[Y�Z[���KO����YH��\H����\]Y[�H\��Y]Y\�[ۜ�������YH��\K]��\Z[��[\����[���[H\�H�\\��R[��[\���ς��\�H�\\�[�[�\���\�ۛH\�KT]ۈ\[�[��Y\�[�[�Hۛ��H\��]XX�[�H\�]ۈ[��[Y��\\\��]�\�\�H�X[
�[؞]\��H�]�YY�X�]\�Kܛ���\]�ܛK[��\]Z\�H�\���Z[[���\��X�\�K�\�HR[��[\��[�[�H�YY��[�H�^[��[ۜ�\��]XX�[�\��]�]]ۋ܈\��X�]H��ۋY]�[�\������[���YY�ۛ���]]ۈ\ˈR[��[\���X�\�\�S���[�\�Y\�]\�H\X�[H�NP�]�[��܈�X[��ˏ�����YH��\K\]ۋ]�\��[ۈ���[�H�X�Y�HHZ[�[][H]ۈ�\��[ۈ[�H\��]�O��ς����\�X�HKH�\\�\���[��ܘ�HHZ[�[][H�\��[ۈ]�[�[YK�H�\��X�X�H\��YH�\��[ۈ�X��]H�و��O���XZ[��˜O���O����O�[\ܝ�\��\��\��\˝�\��[ۗ�[����H
�L
K�]ۈˌL
��\]Z\�Y����O��\��Z[�[[YYX][H�]H�X\�\��܈ۈ�\�]ۈ[��[][ۜ��]\�[�ܘ\�[����Y]�\�HY\[�[�\���H�]H�ۙ�\�[���[�^\��܈܈Z\��[��TH\��܋������YH��\K]\]H�����H\]H[�^\�[���^��[O��ς��[�H�[���\]HH��O��^����O�[�X�K��X�Z[H[�\�H\��]�H�H�[��[��[�\��Z[�ܚ\Y�Z[��\�\�[�[�[ۘ[KHH��O��^����O�\�H\�[Y[�\�Y�X���H��\��H�[K��Y\H�Z[�ܚ\[���\��H�۝����H��O��^����O���܈]]�X]Y�Z[��[�H�Z[�ܚ\[��H[�X�\�H�\�[[����O��^����O�\�H�[X\�H\�Y�X��\��^K]�\�H�Z[\��\��X�X�H���HH��\��H\�X�ܞK������YH��\K\�[]]�KZ[\ܝȏ��[�H\�H�[]]�H[\ܝ�[��YHH�^�\��]�O��ς��Y\ˈH\��]�H�Z]�\�Z�HH�Y�[\�]ۈX��Y�HۈH[\ܝ]��[]]�H[\ܝ�Z�H��O����H�][�[\ܝܙY]���O��ܚ��ܜ�X�H\�ۙ�\�H�[H\�[��[H\�[��YHHX��Y�H
\�X�ܞH�]��O���[�]�˜O���O�H�][�H\��]�K�H��O���XZ[��˜O���O�]H\��]�H���\�H[�[K��HX��Y�HY[X�\���]��[\�HX���]H[\ܝˈ]�\�][��[��YH�X�\�X�ܚY\��]��O���[�]�˜O���O��[�\�H�[]]�H[\ܝ��ܛX[K������YH��\KY^X�]X�H�����HXZ�HH�^��[H\�X�H^X�]X�Hۈ[�^�XX�����ς�����\Έ�\��YH�X�[��[�H�[��Z[[���]��O�[�\��]\�H��\܋ؚ[��[��]یȏ���O���X�ۙ�]H^X�]X�H�]�]��O��[�
�^X\�^����O��Y�\�\�[�H�[��[���O���^X\�^����O�\�X�H�]�]\[����O�]ۏ���O��\���H�X�[��[�H
��O��K�\܋ؚ[��[��]ی����O�H\��\[�Y�H�T�[�\�HKH�T�XY\��YۛܙH\�XY\��]H�\��[�XY�]ۈ^X�[�][��\�H�Y�[�\��]\��\��\����ܚ�ۈ�[�����\�H[�H�YYH��O���]���O�ܘ\\�܈]ۈ][��\��܈�[���ˏ�����YH��ۘ�\�[ۈ���ۘ�\�[ۏ�������\\\���[�H]ۈ\X�][ۈ[��HܝX�H�[��KY�[H^X�]X�H]�[��ۈ[�HXX�[�H�]]ۈ[��[Y�[�H]�HX\��Y���ܙX]H\��]�\����HH��[X[�[�H[����H]ۈ��K�[�H\�KT]ۈ\[�[��Y\�\�[����O�\[��[K]\��]���O��][��H�[���]H��O�[O���O��Y��X���܈[���\]X�H�^[��[ۜ��Y�ܙH�Z[[��[�X��Y�HH�X[�Ո�۝�\�\����H]\����[\����HH
RЈ�[��K\�ܚ\���H][K[YY�X�]H\X�][ۈ�]ޙ[��و\�KT]ۈ\[�[��Y\ˏ�����H�]\�[�^�\\��]]�X]HH�Z[�]H��O�XZ�Y�[O���O�܈H�H\[[�H]�[��[�\��Z[�ܚ\�[��H��O��^����O�Y�Z[��H\��Ջ[�\�Y�]\�H�[X\�H\�Y�X���XYH�[��O��\\���O���[Y[�][ۈ]H�Y�H�΋����˜]ۋ�ܙ����X��\�Kޚ\\�[��΋����˜]ۋ�ܙ����X��\�Kޚ\\�[�O�[�HT

H\�Yۈ��[Y[��܈HX��X�[�X��ܛ�[�ۈ]ۈ�T\X�][ۈ^X�][ۋ������YH��[]YX\�X�\ȏ��[]Y\�X�\�����[��O�H�Y�H�΋��]ۚ�����ܘ[K���K���]�X�Z[X[�\X�\�XK\]ۋ\X��Y�K]�\\Kȏ�����Z[[�X�\�H]ۈX��Y�H�TO�O��O��O�H�Y�H�΋��]ۚ�����ܘ[K���K���]�]�ܚ�]�]^�\Y�[\�Z[�\]ۋȏ�����ܚ��]�T�[\�[�]ۏ�O��O��O�H�Y�H�΋��]ۚ�����ܘ[K���K���]�X�Z[XKX�K]��]�]\]ۋX[�]\\�ȏ�����Z[H�H���]]ۈ[�\\��O��O���[����]���^V��]�����[[�ղ�WE�%�&�uղ�WE�%�6V7F���У����w�F�f���6V���FW"���