What is setup.py?
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/…
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.»
Notice that calling setup.py directly is deprecated. See here for a short description of the new way, and here for a history of python packaging.
10 Answers 10
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 will use setup.py to install your module. Avoid calling setup.py directly.
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/
@PauloOliveira See Distributing Python Modules which describes Distutils, specifically look into 2. Writing the Setup Script.
@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.
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.
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,
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='foomail@foo.example', 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='foomail@foo.example', 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='foomail@foo.example', 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 temporarytest.pypi.org server to make oneself familiarize with the procedure, and then publish it on the permanentpypi.org server for the public to use your package.
- publish straight away on the permanentpypi.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,
- the first step is to locally build the distributions using:
# prereq: wheel (pip install wheel) $ python setup.py sdist bdist_wheel $ 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:
Optionally, you can also sign the files in your package with a GPG by:
Bonus Reading:
Kenneth Reitz (author of the venerable requests ) has this project to explicitly give a good example of setup.py — github.com/kennethreitz/setup.py
@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.
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 ).
So according to the analogy above, if building the module failed for some reason I would tinker with the setup.py script. correct?
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 .
@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 Makefile s 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.
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, . «
If you downloaded package that has «setup.py» in root folder, you can install it by running
If you are developing a project and are wondering what this file is useful for, check Python documentation on writing the Setup Script
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 .
setup.py can be used in two scenarios , First, you want to install a Python package. Second, you want to create your own Python package. Usually standard Python package has couple of important files like setup.py, setup.cfg and Manifest.in. When you are creating the Python package, these three files will determine the (content in PKG-INFO under egg-info folder) name, version, description, other required installations (usually in .txt file) and few other parameters. setup.cfg is read by setup.py while package is created (could be tar.gz ). Manifest.in is where you can define what should be included in your package. Anyways you can do bunch of stuff using setup.py like
python setup.py build python setup.py install python setup.py sdist upload [-r urltorepo] (to upload package to pypi or local repo) There are bunch of other commands which could be used with setup.py . for help
python setup.py --help-commands setup.py is a Python file like any other. It can take any name, except by convention it is named setup.py so that there is not a different procedure with each script.
Most frequently setup.py is used to install a Python module but server other purposes:
Perhaps this is most famous usage of setup.py is in modules. Although they can be installed using pip , old Python versions did not include pip by default and they needed to be installed separately.
If you wanted to install a module but did not want to install pip , just about the only alternative was to install the module from setup.py file. This could be achieved via python setup.py install . This would install the Python module to the root dictionary (without pip , easy_install ect).
This method is often used when pip will fail. For example if the correct Python version of the desired package is not available via pip perhaps because it is no longer maintained, , downloading the source and running python setup.py install would perform the same thing, except in the case of compiled binaries are required, (but will disregard the Python version -unless an error is returned).
Another use of setup.py is to install a package from source. If a module is still under development the wheel files will not be available and the only way to install is to install from the source directly.
Building Python extensions:
When a module has been built it can be converted into module ready for distribution using a distutils setup script. Once built these can be installed using the command above.
A setup script is easy to build and once the file has been properly configured and can be compiled by running python setup.py build (see link for all commands).
Once again it is named setup.py for ease of use and by convention, but can take any name.
Another famous use of setup.py files include compiled extensions. These require a setup script with user defined values. They allow fast (but once compiled are platform dependant) execution. Here is a simple example from the documentation:
from distutils.core import setup from Cython.Build import cythonize setup( name = 'Hello world app', ext_modules = cythonize("hello.pyx"), ) This can be compiled via python setup.py build
Another module requiring a setup script is cx_Freeze . This converts Python script to executables. This allows many commands such as descriptions, names, icons, packages to include, exclude ect and once run will produce a distributable application. An example from the documentation:
import sys from cx_Freeze import setup, Executable build_exe_options = base = None if sys.platform == "win32": base = "Win32GUI" setup( name = "guifoo", version = "0.1", description = "My GUI application!", options = , executables = [Executable("guifoo.py", base=base)]) This can be compiled via python setup.py build .
So what is a setup.py file?
Quite simply it is a script that builds or configures something in the Python environment.
A package when distributed should contain only one setup script but it is not uncommon to combine several together into a single setup script. Notice this often involves distutils but not always (as I showed in my last example). The thing to remember it just configures Python package/script in some way.
It takes the name so the same command can always be used when building or installing.