Python 101: easy_install or how to create eggs

2 Comments / Packaging, Python / By / / Python, Python 101

Today we’re going to take a look at the controversial easy_install method of installing Python modules and packages. We will also learn how to create our own *.egg files. You will need to go get the SetupTools package to follow along. This package doesn’t support Python 3.x so if you need that, see pip or distribute. There will be articles on each of those projects in the future. For now, we’ll be starting with SetupTools and easy_install.

Why is it controversial? I’m not completely certain, but people were not happy with the way it would partially install packages because it doesn’t wait for the download to finish. Also I’ve heard that the author wasn’t very interested in updating it but wouldn’t allow anyone else to update it either. See the Ziade article at the end of this post.

SetupTools is the original mainstream method of downloading and installing Python packages from PyPI and other sources via the command line, kind of like apt-get for Python. When you install SetupTools, it installs a script or exe called easy_install that you can invoke on the command line to install or upgrade packages. It also provides a way to create Python eggs. Let’s spend a little time getting to know this utility.

Using easy_install to Install Packages

Once you have SetupTools installed, you should have easy_install on your path. What this means is that you could be able to open a terminal (Linux) or command line (Windows) and simply run easy_install. Here’s a sample invocation:

easy_install sqlalchemy

This will go out to PyPI and try to download the latest SQLAlchemy from there or from whatever location that the PyPI package page points to. The easy_install script will also install it. One semi-common problem that easy_install is faulted for is that it will attempt to start the install before it has finished downloading the package, which can cause a bad install to occur. The cool thing about easy_install is that if you set up your setup.py file correctly, it can also download dependencies and install those too. So if you install something complex, like TurboGears, you’ll see it install lots of packages. This is one reason why you may want to use virtualenv in that you can make sure you like the new packages and that they work correctly. If they don’t, you just delete the virtualenv folder. Otherwise you’ll have to go into your Python folder and dig around and try to “uninstall” (i.e. delete the folders) it yourself. The other thing that easy_install does when installing the egg is that it adds the egg to an easy-install.pth file in site-packages, so when you uninstall it, you’ll need to edit that too. Fortunately you can use pip to uninstall it for you if you don’t like to do all that fiddling yourself. There is an -uninstall (-u) command, but I’ve heard mixed reports on how well it works.

You can install a package by passing a url directly to easy_install. Another fun feature is that you can tell easy_install which version you want and it will try to install it. Finally, easy_install can install from source archives or from eggs. For a full list of commands, you should read the documentation

Creating an egg

An egg file is a distribution format for Python packages. It’s just an alternative to a source distribution or Windows executable, but it should be noted that for pure Python, the egg file is completely cross-platform. We will take a look at how to create our own egg using the package we created in a previous tutorial. Create a new folder and put the mymath folder inside it. Then create a setup.py file in the parent directory to mymath with the following contents:

from setuptools import setup, find_packages

setup(
    name = "mymath",
    version = "0.1",
    packages = find_packages()
    )

Note that instead of using Python’s distutils’ setup function, we’re using setuptools’ setup. We’re also using setuptools’ find_packages function which will automatically look for any packages in the current directory and add them to the egg. To create said egg, you’ll need to do the following from the command line:

python setup.py bdist_egg

This will generate a lot of output, but when it’s done you’ll see that you have three new folders: build, dist, and mymath.egg-info. The only one we care about is the dist folder in which you fill find your egg file, mymath-0.1-py2.6.egg. Note that on my machine, it picked up my default Python, which was 2.6 and created the egg against that version of Python. The egg file itself is basically a zip file. If you change the extension to “zip”, you can look inside it and see that it has two folders: mymath and EGG-INFO. At this point, you should be able to point easy_install at your egg on your file system and have it install your package.

If you want to, you also use easy_install to upload your egg or source directly to the Python Package Index (PyPI) by using the following commands (copied from docs):

setup.py bdist_egg upload         # create an egg and upload it
setup.py sdist upload             # create a source distro and upload it
setup.py sdist bdist_egg upload   # create and upload both

Wrapping Up

At this point, you should be able to use easy_install or know enough to try one of the alternatives. Personally, I’ve had few issues with it and don’t mind using it. However, we will be taking a look at pip and distribute soon so you’ll be able to learn how to use those too in an upcoming article or two. In the meantime, give easy_install a whirl and see what you think or tell your horror stories in the comments!

Further Reading

2 thoughts on “Python 101: easy_install or how to create eggs”

Comments are closed.