eGenix PyRun

eGenix PyRun - One file Python Runtime

eGenix PyRun combines a Python interpreter with an almost complete Python standard library into a single easy-to-use executable. Now with Python 3.4 support !
Version: 2.1.0


eGenix PyRun is our open source, one file, no installation version of Python, making the distribution of a Python interpreter to run Python based scripts and applications to Unix based systems simple and efficient.

eGenix PyRun's executable only needs 11MB for Python 2 and 13MB for Python 3, but still supports most Python applications and scripts - and it can be compressed to just 3-4MB using upx, if needed.

Compared to a regular Python installation of typically 100MB on disk, eGenix PyRun is ideal for applications and scripts that need to be distributed to containers, VMs, clusters, client installations, customers or end-users.

It makes "installing" Python on a Unix based system as simple as copying a single file.

eGenix has been using eGenix PyRun internally in the mxODBC Connect Server product since 2008 with great success and decided to make it available as a stand-alone open-source product.

We provide both the source archive to build your own eGenix PyRun, as well as pre-compiled binaries for Linux, FreeBSD and Mac OS X, as 32- and 64-bit versions. The binaries can be downloaded manually below, or you can let our automatic install script install-pyrun take care of the installation: ./install-pyrun dir and you're done.

If you'd like to learn more about eGenix PyRun, please see the talk we gave at the EuroPython 2012 conference in Florence. The talk video and slides are available in our presentations section:

eGenix PyRun Talk at EuroPython 2012


  • Small footprint: only about 11 MB in size for Python 2.x and only around 13 MB for Python 3.x. Can be compressed to just 3-4 MB using upx.
  • Python 2.6, 2.7 and 3.4 Support: PyRun works with all popular Python versions. We chose the single source approach for achieving this, but had to drop Python 2.5 support as a result.
  • Cross Platform Support: PyRun runs on the following platforms: Linux, FreeBSD and Mac OS X.
  • Full 64-bit Support: PyRun can be built on both 32-bit and 64-bit builds on all supported platforms.
  • Highly Portable Codebase: in addition to the already supported platforms for PyRun, we provide custom porting services for more exotic platforms.
  • Easy Installation: Simply drop the executable into a directory and start using it. No installers, no packagers and only a minimal set of dependencies needs to be provided.
  • Fully Relocatable: eGenix PyRun uses relative search paths, so you can easily move the installation around.
  • Compatible with setuptools, easy_install, pip: Great care was taken to make sure that PyRun can be used with setuptools et al. Please note that these tools are not designed to be relocatable.
  • Perfect virtualenv replacement: PyRun provides an even better level of isolation from the system installed Python version. Instead of using symlinks and other tricks to create a virtual Python environments, PyRun comes with a complete Python runtime and thus doesn't need to play any tricks.
  • Install a complete Python runtime including dependencies in one go: using our install-pyrun installation bash script, you can install PyRun as well as all dependencies using a single install-pyrun -r requirements.txt run.
  • OpenSource: PyRun is licensed under the eGenix Public License. This makes it possible to integrate PyRun into other open-source or commercial products
  • Commerical Support: eGenix provides commercial support for PyRun, in case you need custom builds, help with the integration or need problem solving support.

System Requirements

eGenix PyRun needs these third party tools to be available on the target machines:

Future versions of PyRun will add more flexibility to the build process to make the requirements more customizable.

If you want to compile PyRun yourself, you will need the development packages of the above tools, a C compiler and a GNU make compatible make installed.

Please note that the binary versions of these libraries also need to be available on the PyRun installation target systems. Most modern Unix  systems have the above libraries installed per default.

Please see the eGenix PyRun User Manual for setup instructions.


eGenix PyRun is covered by the Public License Agreement 1.1.0 which is an Open Source license based on the CNRI Python license. Since PyRun also pulls in Python, the respective Python license also applies to the resulting pyrun binary. See the eGenix PyRun license page for more details.

In simple words, you are free to use the software without paying fees or royalties as long as you give proper attribution and keep the license documents together with the software. Please see the license document for details and consult a lawyer if you have legal questions.


The following documentation is available for eGenix PyRun:

eGenix PyRun User Manual and Reference Guide - HTML and PDF

The manual includes a usage guide, an explanation of the build procedure and discusses a few common use cases.

The PDF file is also available as part of the installation and can be found in the PyRun/Doc/ folder.

Please note that the documentation for this release is not yet as complete and comprehensive as it should be. We're working on it.

For details on how to use Python via eGenix PyRun, please refer to the official Python documentation.


You can use any of the available Python books to learn to use Python with PyRun.


We provide pre-compiled binaries of PyRun for a number of platforms, and also make the sources available, so you can build your own variants.

By downloading, installing or using eGenix PyRun, you agree to the terms and conditions set forth in the Public License Agreement 1.1.0 which is an Open Source license based on the CNRI Python license and the Python license. See the eGenix PyRun license page for more details.

Quick Install Script install-pyrun (Linux, FreeBSD, Mac OS X):

If you want your Unix system to automatically download and install PyRun into a directory, you can use a script that we've written for this purpose. It's called install-pyrun and will detect the correct version for your system, install it and then proceed with the installation of setuptools and pip. Try it:

install-pyrun targetdir

You'll always get the latest version of PyRun, distribute and pip that way. See the virtualenv replacement section below for more details.


After download of the script, your have to make it executable using chmod 755 install-pyrun and move it to a bin/ directory on your PATH. In its simplest form, run ./install-pyrun test. This will install egenix-pyrun, setuptools and pip under the directory test/. The script will provide help when invoked with ./install-pyrun -h. More detailed instructions are available in the documentation.

Windows (x86 - 32/64-bit):

eGenix PyRun currently does not support Windows. We are working on a port, but this is not a high priority at the moment. Patches are welcome !

Linux (i686 - 32-bit):


For instructions on how to install these binary distributions, please see the installation section below.

Linux (x86_64 - 64-bit):


For instructions on how to install these binary distributions, please see the installation section below.

Mac OS X (PPC + Intel - 32-bit):


For instructions on how to install these binary distributions, please see the installation section below.

Mac OS X (Intel - 64-bit):


For instructions on how to install these binary distributions, please see the installation section below.

FreeBSD (i386 - 32-bit):


For instructions on how to install these binary distributions, please see the installation section below.

FreeBSD (amd64 - 64-bit):


For instructions on how to install these binary distributions, please see the installation section below.

Solaris (Intel):

Solaris binaries can be made available on demand.

AIX (PowerPC):

AIX binaries can be made available on demand.

Source Code (to build your own eGenix PyRun):


For instructions on how to install from source code, please see the installation section below.

Other Platforms:

If you need binaries for platforms not mentioned here, please contact for details. It is very likely that we can find a way to help you.

Python Unicode Version (UCS2 vs. UCS4)

Python 2 can be built as narrow Unicode version (UCS2) or wide Unicode version (UCS4). For Python 3, there is only a single UCS4 version.

If you want to interface to system installed Python libraries, you need to download the right variant for your platform. Most Unixes ship with wide Python builds these days (including RedHat and SuSE). In order to make sure, please run the following command which will tell you what kind of Python installation you have:

python -c "import sys;print(sys.maxunicode<66000)and'UCS2'or'UCS4'"

If you get errors such as "unresolved symbol PyUnicodeUCS2_AsEncodedString" when trying to load an extension from eGenix PyRun, you have likely installed a binary for different Unicode version.


For full details on how to install, setup and configure eGenix PyRun, please see the eGenix PyRun User Manual. It is available as PDF for offline reading and HTML for online reading:

eGenix PyRun User Manual and Reference Guide - HTML and PDF

What follows is a short summary:

Windows Installer

eGenix PyRun currently does not support Windows platforms.

Prebuilt Binary Distribution

Simply download a suitable binary distribution for the version of Python and platform you need and extract it to a base directory where you'd like PyRun to live. Then use the eGenix PyRun executable like you'd use a regular Python interpreter, e.g.

You can also put pyrun into the shebang of the script, e.g.
#!/usr/bin/env pyrun2.7
# Hello World Demo
print "Hello World!"

Please note that the binary distributions contain more than just the PyRun executable. They also come with a few extra standard library extensions which are normally not part of PyRun and the include files needed to compile Python extensions for use with PyRun.

If you are just looking for the plain single-file PyRun executable, only extract the file bin/pyrunX.X (with X.X being the underlying Python version, e.g. 2.7) from the binary distributions.

virtualenv replacement: install-pyrun script

To further simplify installation of eGenix PyRun, we've created a bash script which you can use to easily install PyRun in a similar way to how you'd use the virtualenv script. The script is called install-pyrun and available from our download server.

Usage is simple:

./install-pyrun targetdir

The script will download the right PyRun binary distribution for your platform, install it in the targetdir and then download and install distribute and pip.

The script also offers a few options to adjust various parameters, install PyRun from a local directory, select a specific version, skip installation of distribute and pip, etc. The script will output a list of options when run with -h:

./install-pyrun -h

It uses curl to download the packages, so you need to have curl installed on your platform.

Complete Python runtime installation with dependencies

If you want to install PyRun together with pip and all your project dependencies, use the -r requirements.txt option:

./install-pyrun -r requirements.txt targetdir

Shipping external libraries with PyRun

If you want to ship your product with PyRun and need external libraries for PyRun to link against, simply place them into the same directory as the PyRun executable. PyRun comes with an rpath setting to first look in the PyRun binary's directory for share libraries to simplify this often needed setup.

For more details, please see the documentation.

eGenix PyRun Directory Structure

If you want to install other libraries or packages for use in eGenix PyRun, you need to pay a little more attention to where you copy the executable. eGenix PyRun assumes the following directory layout relative to the executable (with X.X being the underlying Python version, e.g. 2.7):

(Python 2) or include/pythonX.Xm (Python 3)

The lib/pythonX.X directory  is used as location of the Python libaries and automatically put on sys.path in case it is available. Optional packages installed through distutils or setuptools will go into the corresponding lib/pythonX.X/site-packages/ directory.

The lib/pythonX.X directory may also contain Python standard library extension modules in the lib-dynload/ sub-directory which are not integrated into the eGenix PyRun executable. The prebuilt binary distributions come with  a set of such extensions.

The include/ directory is only needed in case you want to compile Python C extensions. It is available as part of the prebuilt binary distributions we make available.

Building you own eGenix PyRun binary

In order to build your own version, simply download the above source archive, untar/unzip it to a temporary directory and follow these steps:

cd egenix-pyrun-*
cd PyRun
make install

This will download the Python source distribution and start a build of eGenix PyRun. The result will be installed to the directory /usr/local/ using the directory layout as described above.

If you'd like to build a binary distribution archive, use the following commands instead:

cd egenix-pyrun-*
cd PyRun
make distribution

You can then pick up the distribution archive from the dist/ directory.

Customization Options

If you would rather install to a different directory, you can add the make parameter PREFIX=/path/to/pyrun/, This will cause make to install eGenix PyRun in /path/to/pyrun/.

If you want to build against a specific Python version, you can specify the version using the make parameter PYTHONFULLVERSION=2.7.5. Please have a look at the PyRun/Makefile for more ways of customizing the setup.

For future versions of eGenix PyRun, we plan to make the setup customizable via a top-level file so you can use Python to trigger the build, customize the included standard lib extension modules and installation.


eGenix offers these support options:

Commercial Support

Professional level support for this product as well as all other eGenix products and Python itself is available directly from the developers at

Consulting offers professional consulting services for all questions and tasks around this product, including customized modifications, help with integration and on-site problem solving. Please contact for details.

Free User Support

In order for our users to keep in touch and be able to help themselves, we have created the egenix-users user mailing list.


eGenix PyRun has been in use in production as part of our mxODBC Connect Server client-server database product for many years.

We are pleased to make it available to a wide public.

History & Changes

Please see the change log for details regarding changes to the package between releases.

Older versions of eGenix PyRun, which are still available: