Complete Guide to setup.py Configuration

setup.py is a Python script that serves as the standard way to define metadata about your package and its dependencies, enabling developers to create, configure, and distribute Python packages effectively. It acts as the configuration file that tells the Python packaging tools how to build, install, and manage your package, including information about its name, version, dependencies, and other essential metadata. Modern Python packaging has evolved with alternatives like pyproject.toml, but setup.py remains widely used and important for many existing projects and specific use cases.

Contents

• What is setup.py?
• Basic setup.py Configuration
• Essential Parameters and Options
• Project Structure Requirements
• Modern Alternatives: setup.cfg and pyproject.toml
• Building and Distributing Packages
• Best Practices and Migration

What is setup.py?

setup.py is a Python script that serves as the central configuration file for building and distributing Python packages. According to VPK Technologies, Python packages are a fundamental part of the Python ecosystem, allowing developers to organize and distribute their code effectively, with setup.py being the standard way to define metadata about your package and its dependencies.

The script uses the setup() function from the setuptools module to specify all the information needed for packaging. As Xebia explains, it could even be an empty package; just make sure the package folder exists and contains a file named __init__.py (which may be empty).

setup.py has been the traditional way to configure Python packages, though the ecosystem is evolving. As Python Developer Tooling Handbook notes, in the past, setuptools projects required a setup.py script to be present in the project root. However, this is no longer the case with modern packaging standards.

Basic setup.py Configuration

A basic setup.py file typically imports the necessary components and calls the setup() function with key parameters. Here’s the fundamental structure:

from setuptools import setup, find_packages

setup(
    name="my_package",
    version="0.1.0",
    author="Your Name",
    author_email="your.email@example.com",
    description="A brief description of your package",
    packages=find_packages(),
    install_requires=[
        # List your dependencies here
        "requests>=2.25.1",
    ],
)

As Medium developer Thomas Zilliox demonstrates, the install_requires parameter is where you list your package dependencies. The GeeksforGeeks guide emphasizes that you first need to create a folder named ‘my_package’ with a python file named ‘init.py’ inside it, which will be the root of your package.

Essential Parameters and Options

The setup() function accepts numerous parameters to configure your package comprehensively. Here are the most commonly used ones:

Core Metadata

• name: The name of your package
• version: Version number (semantic versioning recommended)
• description: Brief description of the package
• long_description: Detailed description (often from README)
• author: Author’s name
• author_email: Author’s email address
• url: Project homepage URL
• license: License type (MIT, Apache, etc.)

Package Configuration

• packages: List of packages to include
• find_packages(): Automatically discovers all packages
• package_dir: Mapping of package names to directories
• py_modules: List of single modules to include
• package_data: Additional data files to include

Dependencies and Requirements

• install_requires: Runtime dependencies
• setup_requires: Build-time dependencies
• tests_require: Testing dependencies
• extras_require: Optional dependencies

As Xebia’s practical guide shows, you can also create a setup.cfg file to complement setup.py with additional configuration details, such as flake8 configuration or test settings.

Project Structure Requirements

For a proper Python package using setup.py, you need a specific directory structure. According to Xebia, your project should look something like this:

example_project/
├── exampleproject/    # Python package with source code
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── setup.py
├── README.md
├── LICENSE
└── setup.cfg          # Optional configuration file

The GeeksforGeeks guide explains that the package folder must contain an __init__.py file, which may be empty, to make it a proper Python package. This file can contain all the functions and classes in your package module.

For more complex projects, Xebia suggests you can have other files or folders in the structure, such as a tests/ folder, a .gitignore or a LICENSE file, but these are not strictly required.

Modern Alternatives: setup.cfg and pyproject.toml

While setup.py has been the traditional approach, the Python ecosystem has evolved with more modern configuration options.

setup.cfg

As Ian Hopkinson explains, setup.cfg complements setup.py by serving as a configuration file that defines a package’s metadata and other essential options typically provided to the setup() function. This declarative config used in setup.cfg is more convenient than the script-based approach.

pyproject.toml

According to Towards Data Science, as of PEP-517 and PEP-518, setuptools is no longer the de facto tool that is supposed to be used when packaging Python projects. The pyproject.toml file follows the TOML format and can define build requirements and other project metadata.

A modern pyproject.toml example looks like this:

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "example"
version = "0.1.0"
description = "Example package"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.25.0",
]

As Xebia’s updated guide notes, specifying configuration data in a pyproject.toml file instead of in a separate file allows projects to consolidate their configurations, reducing the overall number of configuration files in the project.

Building and Distributing Packages

Once your setup.py is configured, you can build and distribute your packages using several commands:

Building Packages

• Source distribution: python setup.py sdist
• Wheel distribution: python setup.py bdist_wheel
• Both (recommended): python -m build or python -m build --sdist --wheel

As Xebia explains, the python -m build command will create a dist/ directory and create both a source distribution (sdist, named example-0.0.1.tar.gz) as well as a binary distribution (wheel, named example-0.0.1-py3-none-any.whl).

Installation

To install your package, use:

pip install dist/your_package-0.1.0.tar.gz
# or
pip install dist/your_package-0.1.0-py3-none-any.whl

The Python Developer Tooling Handbook emphasizes that to install a package, you should use pip install rather than python setup.py install.

Testing

As Xebia shows, you can run tests using python setup.py test if you have the necessary dependencies configured in setup.cfg or the script.

Best Practices and Migration

Current Best Practices

1. Use modern build tools: Prefer python -m build over direct python setup.py commands
2. Version control: Include your package in version control systems like Git
3. Semantic versioning: Follow semantic versioning (MAJOR.MINOR.PATCH)
4. Comprehensive metadata: Provide thorough documentation and metadata
5. Testing: Include comprehensive tests and test requirements

Migration to Modern Standards

As Python.org discussions show, many projects are migrating from setup.py to pyproject.toml. This migration involves:

1. Creating a pyproject.toml file with build system configuration
2. Moving setup() parameters to the appropriate TOML sections
3. Removing or minimal setup.py (can be empty for compatibility)

CodeRivers notes that pyproject.toml can define build requirements and other project metadata and is becoming more popular as it follows the emerging trend of using TOML for project configuration in the Python ecosystem.

Sources

1. A Practical Guide To Using Setup.py | Xebia
2. How to Create Python Package with setup.py | VPK Technologies
3. What is setup.py in Python? - GeeksforGeeks
4. Understanding setup.py, setup.cfg and pyproject.toml in Python – SomeBeans
5. Should I run python setup.py? – Python Developer Tooling Handbook
6. How to Build a Python package? - GeeksforGeeks
7. A Practical Guide To Setuptools And Pyproject.toml | Xebia
8. How to Use Python setup.py | Delft Stack
9. setuptools – Python Developer Tooling Handbook
10. Python Packaging Demystified: Practical Tips for Every Developer | Medium

Conclusion

setup.py remains a fundamental tool in Python package development, serving as the traditional way to define package metadata and configuration. While modern alternatives like pyproject.toml are gaining popularity, understanding setup.py is essential for working with existing projects and specific use cases. The key to effective setup.py usage lies in understanding its core parameters, proper project structure, and modern build tools. As the Python packaging ecosystem continues to evolve, developers should stay informed about both traditional setup.py approaches and emerging standards like pyproject.toml to make informed decisions about their packaging strategies.