What is setup.py?

Question

Can anyone please explain what setup.py is and how it can be configured or used?

Solution 1

setup.py is a python file, the presence of which is an indication that the module/package you are about to install has likely been packaged and distributed with Distutils, which is the standard for distributing Python Modules.

This allows you to easily install Python packages. Often it's enough to write:

$ pip install . 

pip will use setup.py to install your module. Avoid calling setup.py directly.

https://docs.python.org/3/installing/index.html#installing-index

Solution 2

It helps to install a python package foo on your machine (can also be in virtualenv) so that you can import the package foo from other projects and also from [I]Python prompts.

It does the similar job of pip, easy_install etc.,

---

Using setup.py

Let's start with some definitions:

Package - A folder/directory that contains __init__.py file. Module - A valid python file with .py extension. Distribution - How one package relates to other packages and modules.

Let's say you want to install a package named foo. Then you do,

$ git clone https://github.com/user/foo
$ cd foo
$ python setup.py install

Instead, if you don't want to actually install it but still would like to use it. Then do,

$ python setup.py develop

This command will create symlinks to the source directory within site-packages instead of copying things. Because of this, it is quite fast (particularly for large packages).

---

Creating setup.py

If you have your package tree like,

foo
├── foo
│   ├── data_struct.py
│   ├── __init__.py
│   └── internals.py
├── README
├── requirements.txt
└── setup.py

Then, you do the following in your setup.py script so that it can be installed on some machine:

from setuptools import setup

setup(
   name='foo',
   version='1.0',
   description='A useful module',
   author='Man Foo',
   author_email='[email protected]',
   packages=['foo'],  #same as name
   install_requires=['wheel', 'bar', 'greek'], #external packages as dependencies
)

Instead, if your package tree is more complex like the one below:

foo
├── foo
│   ├── data_struct.py
│   ├── __init__.py
│   └── internals.py
├── README
├── requirements.txt
├── scripts
│   ├── cool
│   └── skype
└── setup.py

Then, your setup.py in this case would be like:

from setuptools import setup

setup(
   name='foo',
   version='1.0',
   description='A useful module',
   author='Man Foo',
   author_email='[email protected]',
   packages=['foo'],  #same as name
   install_requires=['wheel', 'bar', 'greek'], #external packages as dependencies
   scripts=[
            'scripts/cool',
            'scripts/skype',
           ]
)

---

Add more stuff to (setup.py) & make it decent:

from setuptools import setup

with open("README", 'r') as f:
    long_description = f.read()

setup(
   name='foo',
   version='1.0',
   description='A useful module',
   license="MIT",
   long_description=long_description,
   author='Man Foo',
   author_email='[email protected]',
   url="http://www.foopackage.example/",
   packages=['foo'],  #same as name
   install_requires=['wheel', 'bar', 'greek'], #external packages as dependencies
   scripts=[
            'scripts/cool',
            'scripts/skype',
           ]
)

The long_description is used in pypi.org as the README description of your package.

---

And finally, you're now ready to upload your package to PyPi.org so that others can install your package using pip install yourpackage.

At this point there are two options.

• publish in the temporary test.pypi.org server to make oneself familiarize with the procedure, and then publish it on the permanent pypi.org server for the public to use your package.
• publish straight away on the permanent pypi.org server, if you are already familiar with the procedure and have your user credentials (e.g., username, password, package name)

Once your package name is registered in pypi.org, nobody can claim or use it. Python packaging suggests the twine package for uploading purposes (of your package to PyPi). Thus,

(1) the first step is to locally build the distributions using:

# prereq: wheel (pip install wheel)
$ python setup.py sdist bdist_wheel

(2) then using twine for uploading either to test.pypi.org or pypi.org:

$ twine upload --repository testpypi dist/*
username: ***
password: ***

It will take few minutes for the package to appear on test.pypi.org. Once you're satisfied with it, you can then upload your package to the real & permanent index of pypi.org simply with:

$ twine upload dist/*

Optionally, you can also sign the files in your package with a GPG by:

$ twine upload dist/* --sign

---

Bonus Reading:

• See a sample setup.py from a real project here: torchvision-setup.py

• PEP 517, setuptools

• why twine? using twine

Solution 3

setup.py is Python's answer to a multi-platform installer and make file.

If you’re familiar with command line installations, then make && make install translates to python setup.py build && python setup.py install.

Some packages are pure Python, and are only byte compiled. Others may contain native code, which will require a native compiler (like gcc or cl) and a Python interfacing module (like swig or pyrex).

Solution 4

If you downloaded package that has "setup.py" in root folder, you can install it by running

python setup.py install

If you are developing a project and are wondering what this file is useful for, check Python documentation on writing the Setup Script

Solution 5

setup.py is a Python script that is usually shipped with libraries or programs, written in that language. It's purpose is the correct installation of the software.

Many packages use the distutils framework in conjuction with setup.py.

http://docs.python.org/distutils/

View more solutions

Comments

[Das.Rot]

Eric: Better examples putting everything together would be benefitial

[Colonel Panic]

To me, it's always felt odd how to install the package you extract it and run the script inside, rather than pointing a package manager at what you've downloaded. That would be more natural. stackoverflow.com/questions/1471994/what-is-setup-py/…

[Swapnil Masurekar]

Check out this official documentation link, its clearly explained here

[Oliver Angelil]

looks like setup.py is no longer needed according to the link @SwapnilMasurekar shared. "setup.py used to be required, but can be omitted with newer versions of setuptools and pip."

[Pavel Šimerda]

Then you could use easy_install or similar. Btw, Python has eggs, sort of similar to ruby gems.

[Paulo Oliveira]

I would appreciate if you share your knowledge on how to create or handle this modules? For example, how to create a basic module, or how to test a script on ./mymodule/bin which imports from ./mymodule/libs/

[MonaLisaOverdrive]

So according to the analogy above, if building the module failed for some reason I would tinker with the setup.py script...correct?

[whatnick]

Yes, there might also be some config files you can look at.

[joelostblom]

Correct me if I am wrong, but I believe there is a small difference between the two. python setup.py install actually runs python setup.py build first (so you don't need to run them separately unless in specific cases). I believe make always needs to be run manually prior to running make install.

[ntninja]

@cheflo Actually make does not require any specific parameters (or ordering): It's completely up to the creator of the Makefile which "targets" are available (and in which order they need to be invoked). Since bare Makefiles are (usually) not very portable, they tend to be generated using commands such as ./configure (autotools) or cmake . (cmake) and it's therefor up to these programs to define whether you need to explicitly run make before make install or not.

[Yous]

@PauloOliveira See Distributing Python Modules which describes Distutils, specifically look into 2. Writing the Setup Script.

[Kemin Zhou]

"setuptools is a (largely) drop-in replacement for distutils first published in 2004" from the python doc: docs.python.org/2/distributing/index.html#distributing-index‌​. setup.py is part of setuptools.

[devinbost]

NEVER USE python setup.py install! It breaks your versioning! stackoverflow.com/questions/4324558/…

[devinbost]

See also: stackoverflow.com/questions/4558145/…

[Kemin Zhou]

I need some one to tell me whether we should still use the setup.py any more according to the docs at docs.python.org/3/installing/index.html "While direct use of distutils is being phased out, ..."

[Mike S]

@devinbost makes a rather alarming comment here, but pretty much every answer to this question blithely instructs one to perform python setup.py install. The links don't seem to clear this up, for me. I wonder what to do instead?

[devinbost]

@MikeS I don't know for certain what the workaround is, but I can tell you that running setup.py has led me to nightmare issues that required many hours of cleanup. I'm guessing that building/bundling with pip or conda would be the solution.

[Alvaro Gutierrez Perez]

You could change the link to docs.python.org/3/installing/index.html, which is the non-legacy documentation link, and also it would be good to add a link to packaging.python.org/tutorials/distributing-packages/#setup-‌​py where it expains the purpose of the setup.py file.

[devinbost]

@MikeS You can use pip to install local dependencies into a conda environment, like mentioned here: stackoverflow.com/questions/22312665/…

[Mike S]

Yes, thanks. I've since discovered that pip is the proper/modern tool for installation and will use that going forward.

[boweeb]

Kenneth Reitz (author of the venerable requests) has this project to explicitly give a good example of setup.py -- github.com/kennethreitz/setup.py

[Yuri Feldman]

@devinbost unless installing something not available through pip (e.g. custom-built library)

[fhchl]

What about sub-packages, i.e. folders with modules inside the package?

[Jwan622]

does this handle the requirements.txt as well?

[kmario23]

@Jwan622 You can parse the requirements.txt file and populate an iterable, say requirements and assign this iterable requirements to install_requires. Please see this page setup.py requirements.txt for an example.

[Palec]

Thanks for the python setup.py --help-commands. Very useful when digging into the setup.py.

[Mikolasan]

To install in your home directory: python setyp.py install --user

[Roly Poly]

re: python setup.py register I got "WARNING: Registering is deprecated, use twine to upload instead (pypi.org/p/twine)" trying this method. Looks like something on this page might be useful for registering: packaging.python.org/tutorials/packaging-projects Namely the part under the headline, "Uploading the distribution archives"

[root]

@YuriFeldman it should be noted that even custom libraries can be built into wheel files, which are installable by pip. (I know this because I've done exactly that at work).

[Guimoute]

Will that operation put the downloaded package in site-packages automatically?

[Quantum0xE7]

What about wheels? Wheels is standard now is it not?#

[Quantum0xE7]

What about Wheels?

[TheTechRobo Stands for Ukraine]

Can setup.py be called whatever I want? Like setup_mathmod.py?

[TheTechRobo Stands for Ukraine]

Can setup.py be called whatever I want? Like setup_mathmod.py?

[Ferdinand Beyer]

Yes, setup.py is just a convention

[sinekonata]

So a package is both the name of the multiple directories that contain a init.py and the name of the directory that contains these directories and the setup.py, right? Or is there a better name to differentiate which of the package= ['package', 'package2'] is the main one?

[Jacob Sánchez]

Server response (410): Project pre-registration is no longer required or supported, upload your files instead.

[Timo]

This explains the use of setup.py but according to the top voted answer one should avoid calling it and instead use pip to run/install a python programme/module that has in the root folder setup.py?