I’ve been experimenting a bit with the new zipapp module in python 3.5.

(Yes, it’s 3.5, I use 3.5 now, 3.5 is cool)

From the documentation:

This module provides tools to manage the creation of zip files containing Python code, which can be executed directly by the Python interpreter. The module provides both a Command-Line Interface and a Python API.

So say we have written a little CLI tool. We can now package this up as a single file and execute it. Neat!

§Here is how it works.

First thing to know: If you place a __main__.py, you can execute the directory (package) with python.

Our directory looks like this

├── __main__.py
├── otherfile.py
└── requirements.txt

and our __main__.py like this

1print("hello world")

We can now run python with the app directory as argument:

$> python app
hello world

Another neat feature is that it works even if you zip the app directory.

 1$> pushd app
 2~/src/demo/app ~/src/demo
 3$> zip -r ../app.pyz *
 4  adding: __main__.py (stored 0%)
 5  adding: requirements.txt (stored 0%)
 6$> popd
 8# Now let's run the archive
 9$> python app.pyz
10hello world

We can even add a shebang to the start of the file:

1$> echo '#!/usr/bin/env python' > app.cmd
2$> cat app.pyz >> app.cmd 
3$> chmod +x app.cmd
4$> ./app.cmd
5hello world

And this is how we produce a single-file python executable.

You’ve been able to execute a zipfile with python since before time (it is present in 2.6, so it is oooold). So you should be able to use this just about anywhere you have a somewhat updated python version.

§In Python 3.5

New in Python 3.5 is the zipapp module, which wraps all this functionality in a nice little module. So instead of all the above, we can now just do:

1$> python3.5 -m zipapp --python '/usr/bin/env python' --output app.pyz app
2$> ./app.pyz
3hello world

Which does pretty much what we did above.


Of course this only bundles our own code, what if we have dependencies? Sorry, you’ll have to bundle them yourself. Luckily, this is super easy!

Simply install your dependencies inside your application directory and add it to your sys.path.

You could do it like:

1$> python -m pip install --prefix ./app click
2Collecting click
3  Using cached click-6.2-py2.py3-none-any.whl
4Installing collected packages: click
5Successfully installed click

Resulting in a directory structure like this:

├── lib
│   └── python2.7
│       └── site-packages
│           ├── click
│           └── click-6.2.dist-info
├── __main__.py
└── requirements.txt

(note that i used python2.7)

and in your __main__.py, add it to your sys.path

 1import sys
 2import os
 4    os.path.join(
 5        os.path.dirname(__file__),
 6        'lib',
 7        'python%d.%d' % (sys.version_info.major, sys.version_info.minor),
 8        'site-packages'
 9    )

And you should now be able to load click.

1$> python app
2<module 'click' from '/home/tbug/src/pybundle/app/lib/python2.7/site-packages/click/__init__.pyc'>

Like always, path hacking feels a little dirty, but we’ll manage.


I wrapped the above examples in a neat little shell-script that does all of this for you.

It also contains a hello-world click example.


Now, is this useful? Where should we use it?

I’m not sure. But it is really cool! :)