Search code examples
pythonsetuptoolsdistutilssetup.py

Format of name of a Python package with setuptools

What should be the format of the name argument of setuptools.setup()? Is it free-form so I can use spaces on it?

from setuptools import setup, find_packages

setup(
    name="My Stuff",
    version="0.0.1.dev1",
    packages=find_packages(),
    test_suite='page_peel_tests'
)

Or should it be an identifier?

setup(
    name="MyStuff", # Or my_stuff
    version="0.0.1.dev1",
    packages=find_packages(),
    test_suite='page_peel_tests'
)

May I use hyphens on it?

setup(
    name="my-stuff",
    version="0.0.1.dev1",
    packages=find_packages(),
    test_suite='page_peel_tests'
)

Also, are the rules different between setuptools and distutils?

Solution

  • You can't use spaces. Names are case insensitive, hyphens and underscores are equivalent and there are a few other cases of "confusable" characters treated as equivalent. From PEP 426 on package naming:

    As distribution names are used as part of URLs, filenames, command line parameters and must also interoperate with other packaging systems, the permitted characters are constrained to:

    ASCII letters ( [a-zA-Z] )
ASCII digits ( [0-9] )
underscores ( _ )
hyphens ( - )
periods ( . )

    Distribution names MUST start and end with an ASCII letter or digit.

    There is no difference in this for setuptools and distutils.

    Don't worry about distutils though; setuptools is the way to go. Those tumultuous days are over. As of 2013, "setuptools [is] the default choice for packaging". Here are the packaging tool recommendations and, while the links are broken, the footnotes provide solid information on why setuptools is better and Pip will use it for installation anyway.