Python > Deployment and Distribution > Packaging Python Projects > Creating `setup.py` or `pyproject.toml` files

Creating a `setup.py` file for packaging

This example demonstrates how to create a `setup.py` file for packaging a Python project. setup.py is a crucial file for distributing your Python code, as it contains metadata and instructions for installing your package. It is an older packaging standard which is gradually being superseded by pyproject.toml, but understanding it is still valuable.

Basic `setup.py` Structure

This code snippet creates a basic setup.py file. Let's break down the key parts: * name: The name of your package. * version: The version number of your package. Follow semantic versioning (e.g., 0.1.0, 1.0.0). * packages: A list of packages to include. find_packages() automatically finds all packages within your project. The include argument specifies which packages to search for. * install_requires: A list of dependencies that your package needs. requests and numpy are included as examples. * author and author_email: Your name and email address. * description: A short, one-line description of your package. * long_description: A longer, more detailed description, often read from a README.md file. The long_description_content_type argument specifies the format of the long description. * url: The URL of your project, typically a GitHub repository. * classifiers: Metadata about your package, such as its development status, intended audience, license, and supported Python versions. A full list of classifiers can be found on PyPI.

from setuptools import setup, find_packages

setup(
    name='my_package',
    version='0.1.0',
    packages=find_packages(include=['my_package', 'my_package.*']),
    install_requires=[
        'requests',
        'numpy',
    ],
    author='Your Name',
    author_email='your.email@example.com',
    description='A short description of the package',
    long_description=open('README.md').read(),
    long_description_content_type='text/markdown',
    url='https://github.com/yourusername/my_package',
    classifiers=[
        'Development Status :: 3 - Alpha',
        'Intended Audience :: Developers',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python :: 3',
        'Programming Language :: Python :: 3.7',
        'Programming Language :: Python :: 3.8',
        'Programming Language :: Python :: 3.9',
    ],
)

Concepts Behind the Snippet

The setup.py file is central to Python packaging. It's a Python script that uses the setuptools library to define the package's metadata and installation requirements. When you run commands like python setup.py install or python setup.py sdist, setuptools uses the information in setup.py to build and install your package.

Real-Life Use Case

Imagine you've developed a Python library for data analysis with custom algorithms. You want to share this library with your team or the broader Python community. Creating a setup.py file allows you to package your code into a distributable format (like a wheel or source distribution) that others can easily install using pip.

Best Practices

  • Keep your install_requires list up-to-date with the exact versions of your dependencies. Use version specifiers (e.g., requests>=2.20.0) to ensure compatibility.
  • Include a comprehensive README.md file with a detailed description of your package and usage instructions.
  • Use a .gitignore file to exclude unnecessary files (like .pyc files and virtual environment directories) from your repository.
  • Consider using a virtual environment to isolate your project's dependencies.
  • Test your package thoroughly before distributing it.

When to Use It

Use setup.py when you want to create a distributable Python package. This is essential for sharing your code with others, whether it's within your organization or publicly on PyPI (the Python Package Index).

Alternatives

The modern alternative to setup.py is using pyproject.toml with a build backend like Poetry, Flit, or Hatch. pyproject.toml is a declarative configuration file that specifies the build system and package metadata. It avoids the need for arbitrary code execution during the build process, which can improve security and reproducibility.

Pros and Cons of setup.py

  • Pros: Widely understood and supported, especially in older projects.
  • Cons: Can involve arbitrary code execution, less declarative than pyproject.toml, more complex to manage dependencies compared to modern tools.

← Creating a `requirements.txt` file Creating and Activating Virtual Environments with `venv` →

FAQ

  • What is `find_packages()`?

    `find_packages()` is a function from the `setuptools` library that automatically discovers and lists all packages within your project. It recursively searches for directories containing an `__init__.py` file, which indicates that the directory is a Python package.
  • How do I build a distribution package?

    Navigate to the directory containing your `setup.py` file in your terminal and run `python setup.py sdist bdist_wheel`. This will create a source distribution (sdist) and a wheel distribution (bdist_wheel) in the dist directory.
  • How do I install my package locally?

    Navigate to the directory containing your `setup.py` file in your terminal and run `pip install .` or `python setup.py install`.