setuptools Quickstart¶

Installation¶

To install the latest version of setuptools, use:

Python packaging at a glance¶

The landscape of Python packaging is shifting and Setuptools has evolved to only provide backend support, no longer being the de-facto packaging tool in the market. All python package must provide a pyproject.toml and specify the backend (build system) it wants to use. The distribution can then be generated with whatever tools that provides a build sdist -alike functionality. While this may appear cumbersome, given the added pieces, it in fact tremendously enhances the portability of your package. The change is driven under PEP 517. To learn more about Python packaging in general, navigate to the bottom of this page.

Basic Use¶

For basic use of setuptools, you will need a pyproject.toml with the exact following info, which declares you want to use setuptools to package your project:

Then, you will need a setup.cfg or setup.py to specify your package information, such as metadata, contents, dependencies, etc. Here we demonstrate the minimum

This is what your project would look like:

Then, you need an builder, such as PyPA build which you can obtain via pip install build . After downloading it, invoke the builder:

You now have your distribution ready (e.g. a tar.gz file and a .whl file in the dist directory), which you can upload to PyPI!

Of course, before you release your project to PyPI, you’ll want to add a bit more information to your setup script to help people find or learn about your project. And maybe your project will have grown by then to include a few dependencies, and perhaps some data files and scripts. In the next few sections, we will walk through those additional but essential information you need to specify to properly package your project.

Automatic package discovery¶

For simple projects, it’s usually easy enough to manually add packages to the packages keyword in setup.cfg . However, for very large projects , it can be a big burden to keep the package list updated. setuptools therefore provides two convenient tools to ease the burden: find: and find_namespace: . To use it in your project:

When you pass the above information, alongside other necessary ones, setuptools walks through the directory specified in where (omitted here as the package reside in current directory) and filters the packages it can find following the include (default to none), then remove those that match the exclude and return a list of Python packages. Note that each entry in the [options.packages.find] is optional. The above setup also allows you to adopt a src/ layout. For more details and advanced use, go to Package Discovery and Namespace Package

Entry points and automatic script creation¶

Setuptools support automatic creation of scripts upon installation, that runs code within your package if you specify them with the entry_points keyword. This is what allows you to run commands like pip install instead of having to type python -m pip install . To accomplish this, add the entry_points keyword in your setup.cfg :

When this project is installed, a main script will be installed and will invoke the some_func in the __init__.py file when called by the user. For detailed usage, including managing the additional or optional dependencies, go to Entry Points .

Dependency management¶

setuptools supports automatically installing dependencies when a package is installed. The simplest way to include requirement specifiers is to use the install_requires argument to setup.cfg . It takes a string or list of strings containing requirement specifiers (A version specifier is one of the operators , =, == or !=, followed by a version identifier):

When your project is installed, all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed. This, of course, is a simplified scenarios. setuptools also provide additional keywords such as setup_requires that allows you to install dependencies before running the script, and extras_requires that take care of those needed by automatically generated scripts. It also provides mechanisms to handle dependencies that are not in PyPI. For more advanced use, see Dependencies Management in Setuptools

Including Data Files¶

The distutils have traditionally allowed installation of “data files”, which are placed in a platform-specific location. Setuptools offers three ways to specify data files to be included in your packages. For the simpliest use, you can simply use the include_package_data keyword:

This tells setuptools to install any data files it finds in your packages. The data files must be specified via the distutils’ MANIFEST.in file. For more details, see Data Files Support

Development mode¶

setuptools allows you to install a package without copying any files to your interpretor directory (e.g. the site-packages directory). This allows you to modify your source code and have the changes take effect without you having to rebuild and reinstall. This is currently incompatible with PEP 517 and therefore it requires a setup.py script with the following content:

This creates a link file in your interpretor site package directory which associate with your source code. For more information, see: (WIP)

Uploading your package to PyPI¶

After generating the distribution files, next step would be to upload your distribution so others can use it. This functionality is provided by twine and we will only demonstrate the basic use here.

Transitioning from setup.py to setup.cfg В¶

To avoid executing arbitary scripts and boilerplate code, we are transitioning into a full-fledged setup.cfg to declare your package information instead of running setup() . This inevitably brings challenges due to a different syntax. Here we provide a quick guide to understanding how setup.cfg is parsed by setuptool to ease the pain of transition.

Resources on Python packaging¶

Packaging in Python is hard. Here we provide a list of links for those that want to learn more.

Getting Started With setuptools and setup.py В¶

setuptools is a rich and complex program. This tutorial will focus on the bare minimum basics you need to get setuptools running so you can:

• Register your package on pypi.
• Build egg, source, and window installer ‘distributables’.
• Upload these ‘distributables’ to pypi.

Installing setuptools and easy install¶

To install setuptools visit http://pypi.python.org/pypi/setuptools and follow the instructions for your operating system. Also, check out http://peak.telecommunity.com/DevCenter/EasyInstall for more instructions on how to install setup tools.

Currently (as of November, 2009), setuptools is pretty easy to install for Python version 2.3 through 2.6.

Bootstrapping setuptools¶

If you are having trouble setting up setuptools for your platform, you may want to check out the ‘bootstrap’ setuptools script at http://peak.telecommunity.com/dist/ez_setup.py.

You can run this like this:

and it will install setuptools for whichever version of Python python refers to. For example on windows:

will install a setuptools for your python24 distribution.

Setting up setup.py В¶

All the features of what can go into a setup.py file is beyond the scope of this simple tutorial. I’ll just focus on a very basic and common format needed to get this project onto pypi.

The contents of setup.py is just pure python:

Directory Structure¶

The directory structure, so far, should look like this:

README¶

A nice idea stolen from http://pypi.python.org/pypi/Sphinx-PyPI-upload is to include a README text file which your code. This would be visible when someone, say, cloned your repo.

Using the simple read function, it is easy to include this in the long_description keyword arg for the setuptools.setup() function.

Classifiers¶

A really nice website is http://pypi.python.org/pypi?%3Aaction=list_classifiers which lists all the classifiers you can use in the setup call.

A sample of this website is:

Using setup.py В¶

The basic usage of setup.py is:

To see all commands type:

And you will get:

Intermezzo: .pypirc file and gpg¶

In order to interact with pypi, you first need to setup an account. Go to http://pypi.python.org/pypi and click on Register .

Now, once registered, when you run setup.py commands that interact with pypi you’ll have to enter your username and password each time.

To get around this, place a .pypirc file in your $HOME directory on linux. On windows, an you’ll need to set a HOME environ var to point to the directory where this file lives.

The structure of a .pypirc file is pretty simple:

There’s probably away around having your plain text password in this file, but I don’t know of the solution and haven’t looked into it.

Also, you often want to sign the files using gpg encryption. Visit http://www.gnupg.org/ on linux or http://www.gpg4win.org/ on windows to install this software.

Registering Your Project¶

With your setup.py and .pypirc in place, registering your project is pretty simple. Just type:

I would say more, but it is just that simple.

Uploading Your Project¶

There are three major setup.py commands we will use:

• bdist_egg : This creates an egg file. This is what is necessary so someone can use easy_install your_project .
• bdist_wininst : This will create an .exe that will install your project on a windows machine.
• sdist : This create a raw source distribution which someone can download and run python setup.py directly.

A key point here is you need to run these commands with the version of python you want to support. We’ll cover this in the Putting It All Together With The Full Windows Script below.

You can run these commands by themselves and simply create the files but not upload them. However, for this project, we always marry these commands with the upload directive which will both build and upload the necessary files.

Putting It All Together With The Full Windows Script¶

This project was build on a windows machine. To best understand how it all works and the other options used when using setup.py let’s just look at the .bat file I use to build the package and upload it to pypi:

For linux, it would be pretty much the same commands, just changing around the directories to point to the correct python versions.

I use the set HOME=C:\Users\Owner\ instead of setting an environ variable on windows

How to get setuptools and easy_install?

I downloaded the ez_setup code from here: http://peak.telecommunity.com/dist/ez_setup.py and ran it, but i don’t think setuptools was properly installed. When i try to open an egg using easy_install i am getting a NameError. Any thoughts?

Here is the specific error:

8 Answers 8

For linux versions(ubuntu/linux mint), you can always type this in the command prompt:

sudo apt-get install python-setuptools

this will automatically install eas-_install

For python3 on Ubuntu

please try to install the dependencie with pip, run this command:

you’d also want to install the python packages.

I’m assuming you’re on Windows (could be wrong) but if you click the green Downloads button, it should take you to a table where you can choose to download a .exe version of setuptools appropriate for your version of Python. All that eggsetup stuff should be taken care of in the executable file.

Let me know if you need more help.

On Ubuntu until python-distribute is something newer than 0.7 I’d recommend:

For Amazon Linux AMI

If you are installing from distro packages, then this probably doesn’t apply to your scenario.

recompile python

I have multiple versions of Python built from source installed, and I found I didn’t have setuptools for version 3.5. It seems like I was missing the zlib libraries when I compiled 3.5, which subsequently made the setuptools install fail quietly (to me at least). Recompiling with the zlib libs installed fixed this for me.

install from GitHub

If you are for some reason missing setuptools and have Python compiled with all the necessary libs, you should be able to install it from the GitHub repo like this:

Installing SetupTools on 64-bit Windows

I’m running Python 2.7 on Windows 7 64-bit, and when I run the installer for setuptools it tells me that Python 2.7 is not installed. The specific error message is:

My installed version of Python is:

I’m looking at the setuptools site and it doesn’t mention any installers for 64-bit Windows. Have I missed something or do I have to install this from source?

11 Answers 11

Apparently (having faced related 64- and 32-bit issues on OS X) there is a bug in the Windows installer. I stumbled across this workaround, which might help — basically, you create your own registry value HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Python\PythonCore\2.6\InstallPath and copy over the InstallPath value from HKEY_LOCAL_MACHINE\SOFTWARE\Python\PythonCore\2.6\InstallPath . See the answer below for more details.

If you do this, beware that setuptools may only install 32-bit libraries.

NOTE: the responses below offer more detail, so please read them too.

Problem: you have 64-bit Python, and a 32-bit installer. This will cause problems for extension modules.

The reasons why the installer doesn’t finds Python is the transparent 32-bit emulation from Windows 7. 64-bit and 32-bit programs will write to different parts of the Windows registry.

This means that the 64-bit Python installer writes to HKLM\SOFTWARE\Python , but the 32-bit setuptools installer looks at HKLM\SOFTWARE\wow6432node\Python (this is handled by windows automatically, programs don’t notice). This is expected behavior and not a bug.

Usually, you have these choices:

• the «clean» way: use 32-bit Python if you have to use 32-bit modules or extensions
• the other «clean» way: only use 64-bit installers when using 64-bit Python (see below)
• what the answer above suggests: copy HKLM\SOFTWARE\Python to HKLM\SOFTWARE\wow6432node\Python , but this will cause problems with binary distributions, as 64-bit Python can’t load 32-bit compiled modules (do NOT do this!)
• install pure Python modules with setuptools instead of the distutils installer (easy_install or pip)

For setuptools itself, for example, you can’t use a 32-bit installer for 64-bit Python as it includes binary files. But there’s a 64-bit installer at http://www.lfd.uci.edu/

gohlke/pythonlibs/ (has many installers for other modules too). Nowadays, many packages on PyPi have binary distributions, so you can install them via pip.