> For the complete documentation index, see [llms.txt](https://a7246c5516ab4c80cdfe21ca2be3e40c.gitbook.io/python-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://a7246c5516ab4c80cdfe21ca2be3e40c.gitbook.io/python-docs/zipapp.md).

# zipapp

***

**What is zipapp and what does it do?**

zipapp creates zip files from directories containing Python files which can be later run by the `Python` interpreter (the program that runs python code). In short, if you have a folder with Python files, you can bundle them into a single executable zip file.

**Command-Line Interface**\
To use it from the command line:

```bash
python -m zipapp myapp -m "myapp:main"
python myapp.pyz
```

This will run the `main` function from the `myapp` file inside the `myapp.pyz` archive.

The command-line arguments to `zipapp` are as follows:

* `-o / --output`: Specify the output zip file name. (default: `<source>.pyz`)
* `-p / --python`: Add an interpreter line to be run when the zipfile is executed. Make the file executable on POSIX systems. (default: no interpreter line)
* `-m / --main`: Write a `__main__.py` file to the archive. It will execute the specified callable function (default: none)
* `-c / --compress`: Compress the files in the archive to reduce its size. (default: no compression)
* `--info`: Display interpreter line in the archive for diagnostic purposes.

**Python API**\
The `zipapp` module defines functions for creating zip archives from directories:

```python
import zipapp
zipapp.create_archive("myapp", "myapp.pyz", interpreter="python3")
```

This will create a zip file named `myapp.pyz` from directory `myapp` using `python3` as the interpreter.

**Real-World Applications**

* Creating portable python applications that can be shared and run on any system with Python installed
* Distributing libraries as zip files that can be directly imported into other Python projects
* Packaging scripts for deployment on servers or embedded systems

**Potential Applications**

* Creating custom installers for python applications
* Packaging GUI scripts for easy distribution
* Automating tasks with python scripts that can be run from the command line

***

### Creating Application Archives with Python's zipapp Module

#### What is an Application Archive?

An application archive is a single file that contains all the files needed to run a Python program. It's like a self-contained package that makes it easy to distribute and execute your program on any computer with Python installed.

#### Creating an Archive from a Directory

To create an archive from a directory, simply use the `create_archive()` function and provide the source directory as the first argument:

```python
import zipapp

source_dir = "my_program"
target_file = "my_program.pyz"
zipapp.create_archive(source_dir, target=target_file)
```

This will create a `my_program.pyz` file containing all the files from the `my_program` directory.

#### Setting the Interpreter

You can also specify the Python interpreter to be used when executing the archive:

```python
interpreter = "/usr/bin/python3"
zipapp.create_archive(source_dir, interpreter=interpreter, target=target_file)
```

This ensures that the program will run with the specified interpreter, even if the user has a different default interpreter installed.

#### Setting the Main Program

If your archive contains a directory but no `__main__.py` file, you can specify the main program to be executed:

```python
main = "my_program.module:main"
zipapp.create_archive(source_dir, main=main, target=target_file)
```

This will make the `my_program.module:main` function the entry point of the program.

#### Filtering Files

You can use a filter function to control which files are included in the archive:

```python
def filter_func(path):
    return path.suffix == ".py"

zipapp.create_archive(source_dir, filter=filter_func, target=target_file)
```

This filter will only include files with the `.py` extension in the archive.

#### Compressing Files

By default, files are stored uncompressed in the archive. To compress them, set the `compressed` argument to `True`:

```python
zipapp.create_archive(source_dir, compressed=True, target=target_file)
```

This will reduce the size of the archive, but it may take longer to create and extract.

#### Real-World Applications

Application archives are useful for:

* **Distributing programs:** Create a single file that can be easily shared and installed on other computers.
* **Creating portable programs:** Run your program on any computer without having to install Python or any dependencies.
* **Packaging web applications:** Combine all the necessary files for a web application into a single archive that can be deployed to a web server.

***

**zipapp - Python Zip Application Archive Format**

**Introduction**

zipapp is a module in Python that allows you to create and work with self-contained Python programs packaged as ZIP archives.

**Creating a Standalone Python Application**

1. **Create Your Application:**
   * Create a directory with your application code, including a `__main__.py` file.
2. **Install Dependencies:**
   * Install all application dependencies using pip into the application directory:

     ```Bash
     python -m pip install -r requirements.txt --target myapp
     ```
3. **Package the Application:**
   * Package your application into a ZIP archive using zipapp:

     ```Bash
     python -m zipapp -p "interpreter" myapp
     ```
   * This creates a `myapp.pyz` file that contains all the application code and dependencies.

**Executing the Application**

* On Unix, the `myapp.pyz` file is executable directly.
* On Windows, the `myapp.pyz[w]` file is executable due to Python registering the `.pyz` and `.pyzw` extensions.

**Modifying the Shebang Line**

The shebang line is the first line of the archive, and it specifies the interpreter to use for executing the application.

* By default, the interpreter used is `/usr/bin/env python`.
* You can specify a custom interpreter using the `-p` option when creating the archive:

  ```Bash
  python -m zipapp -p "/usr/bin/python3" myapp
  ```
* Note that you need to ensure the specified interpreter is available on the target system.

**Real-World Applications**

* Distributing cross-platform Python applications as a single file.
* Creating portable command-line utilities.
* Packaging Python scripts for execution in non-Python environments.

**Caveats**

* C extensions cannot be included in the ZIP archive.
* You may need to manually add non-Python dependencies to `sys.path` if they are not included in the archive.

**Python Zip Application Archive Format**

A Python zip application archive consists of:

1. **Optional Shebang Line:**
   * Contains the `#!` syntax followed by the interpreter path.
   * Allows the archive to be executed directly.
2. **Standard ZIP File Data:**
   * Includes a `__main__.py` file at the root of the archive.
   * Can contain compressed or uncompressed data.

**Code Example**

```Python
# Create an example application
import os

with open("myapp/main.py", "w") as f:
    f.write("print('Hello world!')")

os.system("python -m pip install --target myapp pillow")
os.system("python -m zipapp -p /usr/bin/python3 myapp")
```

This creates a `myapp.pyz` file that can be executed using `/usr/bin/python3`.