🐶
Python

Understanding Python's setup.py: A Guide

By Filip on 10/04/2024

Learn how setup.py is used to package and distribute Python projects, making installation and sharing seamless.

Understanding Python's setup.py: A Guide

Table of Contents

Introduction

In the world of Python, sharing is caring, and that's where setup.py comes in. This special file acts like a passport for your Python project, making it easy for others to install and use your code. It's like a friendly guide for tools like pip, explaining how to package and distribute your project. The core of setup.py is the setup() function, which acts as a project profile. You provide details like your project's name, version, a brief description, the author's name, and any packages it contains. You also list any external packages your project relies on, ensuring everything works smoothly. Let's illustrate with a simple example. Imagine you have a project named 'myproject'. Your setup.py file would look something like this:

Step-by-Step Guide

setup.py is a Python file that lives in the root of your project directory. It acts as the bridge between your project code and the outside world, allowing others to easily install and use your Python project.

Think of it like an instruction manual for packaging and distributing your project. It tells tools like pip how to build, install, and distribute your project.

At the heart of setup.py is the setup() function. This function takes a bunch of arguments that describe your project, such as:

  • name: The name of your project.
  • version: The current version of your project.
  • description: A short description of what your project does.
  • author: Your name (or the project maintainer's name).
  • packages: A list of Python packages in your project.
  • install_requires: A list of other Python packages that your project depends on.

Here's a simple example:

from setuptools import setup, find_packages

setup(
    name='myproject',
    version='0.1.0',
    description='My awesome Python project',
    author='Your Name',
    packages=find_packages(),
    install_requires=['requests'],
)

With a setup.py file in place, you can do things like:

  • Build a source distribution: python setup.py sdist
  • Build a wheel distribution: python setup.py bdist_wheel
  • Install your project locally: python setup.py install

While setup.py has been the traditional way to manage Python projects, the Python packaging landscape is evolving. The use of pyproject.toml is becoming increasingly popular, offering a more declarative and standardized approach to project configuration. However, setup.py is still widely used and understanding its role is valuable for working with many existing Python projects.

Code Example

This Python code defines a setup script for a project named 'myproject'. It specifies metadata like the project's version, description, and author. The script uses setuptools to automatically find all packages within the project and defines 'requests' as a dependency, requiring at least version 2.20.0. This setup script enables the project to be packaged and installed using tools like pip.

from setuptools import setup, find_packages

setup(
    name='myproject',
    version='0.1.0',
    description='My awesome Python project',
    author='Your Name',
    # Find all packages automatically
    packages=find_packages(), 
    # Project dependencies
    install_requires=[
        'requests>=2.20.0',  # Example: Specify a minimum version
    ],
)

Explanation:

  1. Import Necessary Functions:

    • from setuptools import setup, find_packages: This line imports the setup function (the core of the setup process) and the find_packages function (to automatically discover packages within your project).
  2. Call the setup() Function:

    • setup(...): This is where you provide all the information about your project.
  3. Project Metadata:

    • name='myproject': The name of your project (should be a short, lowercase identifier).
    • version='0.1.0': The current version of your project (follow semantic versioning).
    • description='My awesome Python project': A brief description of your project.
    • author='Your Name': Your name or the project maintainer's name.
  4. Package Discovery:

    • packages=find_packages(): This line automatically finds and includes all Python packages (directories containing __init__.py files) within your project.
  5. Dependencies:

    • install_requires=['requests>=2.20.0']: This list specifies that your project depends on the requests library. The >=2.20.0 part ensures that at least version 2.20.0 or higher of requests is installed.

How to Use This setup.py:

  1. Save the code: Save this code as setup.py in the root directory of your Python project.
  2. Create a source distribution: Open your terminal or command prompt, navigate to your project directory, and run:
    python setup.py sdist
    This will create a compressed archive (usually a .tar.gz file) in a new dist directory.
  3. Install your project:
    python setup.py install
    This will install your project into your Python environment, making it available for use.

Key Points:

  • find_packages(): This function simplifies package management by automatically finding packages in your project.
  • install_requires: Clearly defining your project's dependencies makes it easy for others to install your project with all its requirements.
  • Distribution: The sdist command creates a source distribution that can be used to install your project in different environments.
  • Evolution of Packaging: While setup.py is still widely used, consider exploring newer tools like pyproject.toml for a more modern approach to Python packaging.

Additional Notes

  • Purpose: The primary goal of setup.py is to provide a standardized way to describe your project's structure and dependencies, making it installable and distributable.
  • setuptools vs. distutils: While distutils was the original packaging library, setuptools is now the recommended choice. It offers more features and better compatibility.
  • Beyond the Basics: The setup() function accepts many more arguments for customizing the build process, including:
    • long_description: A detailed description of your project (often from a README file).
    • url: The project's website or repository URL.
    • classifiers: Keywords categorizing your project on PyPI.
    • entry_points: Define scripts your package provides.
  • Version Control: It's crucial to update the version number in setup.py with each release to maintain compatibility and track changes.
  • Testing: Before distributing your project, thoroughly test the installation process to ensure everything works as expected.
  • Alternatives: While pyproject.toml is gaining traction, setup.py remains relevant, especially when working with legacy projects. Understanding both is beneficial.
  • Community Resources: The Python Packaging User Guide (https://packaging.python.org/) is an excellent resource for in-depth information on packaging and distributing Python projects.

Remember, a well-crafted setup.py file is essential for making your Python project accessible and usable by others.

Summary

The setup.py file is a crucial part of Python projects, acting as a bridge between your code and the outside world. It provides instructions for packaging and distributing your project, allowing others (and tools like pip) to easily install and use it.

Key Features:

  • Project Metadata: Defines essential information about your project, including its name, version, description, and author.
  • Dependency Management: Specifies the packages your project depends on using install_requires, ensuring they are installed alongside your project.
  • Packaging Instructions: Enables the creation of source distributions (using sdist) and wheel distributions (using bdist_wheel) for sharing and distribution.
  • Local Installation: Allows you to install your project locally using install.

Core Component:

The heart of setup.py is the setup() function, which takes arguments describing your project. This includes details like the project's name, version, packages, and dependencies.

Evolving Landscape:

While setup.py remains widely used, the Python packaging landscape is shifting towards newer tools like pyproject.toml. However, understanding setup.py is still valuable for working with existing projects and grasping the fundamentals of Python packaging.

Conclusion

In conclusion, setup.py serves as the backbone of a Python project's distribution, acting as a guide for packaging and installation. It allows developers to specify project metadata, manage dependencies, and create distributable packages. While newer tools like pyproject.toml are emerging, setup.py remains a cornerstone of the Python packaging ecosystem, especially for interacting with legacy projects. Understanding its role is essential for any Python developer looking to share their work with the world.

References

  • Packaging and distributing projects - Python Packaging User Guide Packaging and distributing projects - Python Packaging User Guide | Dec 14, 2023 ... It's the file where various aspects of your project are configured. The primary feature of setup.py is that it contains a global setup() ...
  • What is setup.py in Python? - GeeksforGeeks What is setup.py in Python? - GeeksforGeeks | A Computer Science portal for geeks. It contains well written, well thought and well explained computer science and programming articles, quizzes and practice/competitive programming/company interview Questions.
  • What is the actual use of setup.py? : r/learnpython What is the actual use of setup.py? : r/learnpython | Posted by u/Aspire26 - 31 votes and 10 comments
  • What is setup.py? What is setup.py? | Contributor: Shittu Olumide Ayodeji
  • Python Setup.py - Python Cheatsheet Python Setup.py - Python Cheatsheet | The setup script is the centre of all activity in building, distributing, and installing modules using the Distutils. The main purpose of the setup script is to describe your module distribution to the Distutils, so that the various commands that operate on your modules do the right thing.
  • Removing setup.cfg and setup.py from the packaging tutorial ... Removing setup.cfg and setup.py from the packaging tutorial ... | TL;DR: is it time to just use pyproject.toml, and which build backend should be recommended? With many build backends now implementing PEP 621 (including PyPA’s setuptools, hatch, and flit), there’s a desire to simplify and modernize the packaging tutorial to just use pyproject.toml. However, there’s been a lot of discussion about the scope of that, and there are currently two PR’s that take different approaches: #1031 shows how to use different build backends, and currently recommends hatch...
  • Please do not remove setup.py install as it is needed for ... Please do not remove setup.py install as it is needed for ... | As requested in #510 (comment) I'm opening a new issue. What I'd like for is that setup.py install --root=... (or a minimal equivalent) remains working as a 'low-level' install command for distribu...
  • Which fields are required for a setup.py? Especially, is author ... Which fields are required for a setup.py? Especially, is author ... | Hi, what is the absolute minimum of a setup.py for a package to upload to PyPi? I could not find a dedicated list. Background: I ported a very old Python package back from 2003 to Python 3 and I’d like to release it on PyPi. Obviously, now I am the maintainer, but not the author. I tried to add author to setup.py, but then both python setup.py check and pep517 warn me about the missing author_email field which I do not know - and most probably the author does not want to get involved in th...
  • actions/setup-python: Set up your GitHub Actions workflow ... - GitHub actions/setup-python: Set up your GitHub Actions workflow ... - GitHub | Set up your GitHub Actions workflow with a specific version of Python - actions/setup-python

Were You Able to Follow the Instructions?

😍Love it!
😊Yes
😐Meh-gical
😞No
🤮Clickbait