Skip to content
A simple tool for turning a multi-file, multi-dependency Python script into a single file.
Python Shell
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples/readme Made the examples actually use Clint. Nov 5, 2013
utils Added clean utility. Nov 30, 2013
.gitignore Added super zips and virtual envs to gitignore. Nov 8, 2013
.travis.yml Removed smoke test in travis script. Nov 17, 2013
LICENSE Added license. Jun 19, 2013 Added test for requirements file. Nov 29, 2013
README.rst Updated username from brownhead to itsjohncs. Nov 24, 2018
VERSION Released 1.0-rc.1. Nov 3, 2013 Updated username from brownhead to itsjohncs. Nov 24, 2018
tox.ini Added some acceptance tests. Nov 17, 2013


Super Zippy

Super Zippy takes a Python package and its pure Python dependencies and transforms them all into a single executable file.

Linux and Mac OS X are the only operating systems that are officially supported right now. It seems like Superzippy should work for any operating system though, so feel free to try it on your own (and let me know if you want to help testing!).


Say I'm trying to write a Python script that uses Clint to provide nice console output. I can create a project with a directory tree as below (this example is in the repo under examples/readme/).

+ tinyscript/
|   +
|   +

The file establishes the Clint dependency and is very short. This file must exist because Super Zippy will use pip to install your package, and pip needs this file.

from setuptools import setup, find_packages
    name = "tinyscript",
    packages = find_packages(),
    install_requires = ["Clint"]

The file is empty (see here for info).

Finally, the file has our actual script.

from clint.textui import puts, colored
import sys

def foo():
    puts("I am a mighty foo function!"))

def bar():
    puts("Nice to meet you, I am bar."))

if __name__ == "__main__":
    puts("Running as a script!")

We can now use Super Zippy.

$ ls tinyscript/
$ superzippy . tinyscript.main:foo
$ ls tinyscript/
$ ./
I am a mighty foo function!
$ echo $?

Note that "I am a mighty foo function!" above is displayed in red if you actually run it.

If we'd like to have the bar() function be our entry point (rather than the foo() function above), we could run

$ superzippy . tinyscript.main:bar
$ ./
Nice to meet you, I am bar.
$ echo $?

There's a number of options you can give Super Zippy and you can get an up-to-date listing of them by running superzippy -h.


You can install Super Zippy from pip easily (see here for installing pip). This will grab the latest stable release.

$ pip install superzippy

Alternatively, you can install the most recent version off of GitHub.

$ git clone
$ cd superzippy/
$ python install

If you are planning to do development on Super Zippy, you may want to install Super Zippy in editable mode. You can do this by running python develop instead of python install.

You can of course also use Super Zippy on itself to make a Super Zip of Super Zippy. Though doing this automatically may be done in the future, it seems mostly unecessary at the moment to add this into our release process.

How it Works

Super Zippy's algorithm is fairly straightforward.

  1. Create a virtual environment using virtualenv.
  2. Install all the desired packages into the virtual environment using pip.
  3. Grab the site-packages directory out from the virtual environment (which is the directory that contains all installed packages) and put it in an empty temporary directory.
  4. Add a file to the temporary directory that executes the desired function.
  5. Zip the temporary directory up.
  6. Make the zip file executable by flipping the executable bit and adding #!/usr/bin/env python to the beginning of the zip file.

Adding a shebang to the beginning of the zip file doesn't affect our ability to decompress it because a zip file's "header" is located at the back of the file (see this wikipedia article).

Who Made This?

My name is John Sullivan and I created this over a couple weekends with the assistance of Chris Manghane. After the initial release, Steven Myint graciously submitted several useful patches as well.

If you are interested in helping with the development, feel free to fork and dive in! If you'd just like to send me a message you can find my contact information on my portfolio at


Apache License v2.0 (see LICENSE for full text).

If you need a more permissive license please open up an issue in the tracker that describes your desired use case.

You can’t perform that action at this time.