Package Configuration

Projects set up with PyScaffold rely on setuptools, and therefore can be easily configured/customised via setup.cfg. Check out the example below:

# Docs on setup.cfg:

name = my_project
description = A test project that was set up with PyScaffold
author = Florian Wilhelm
author-email =
license = MIT
url = https://...
long-description = file: README.rst
platforms = any
classifiers =
    Development Status :: 5 - Production/Stable
    Topic :: Utilities
    Programming Language :: Python
    Programming Language :: Python :: 3
    Environment :: Console
    Intended Audience :: Developers
    License :: OSI Approved :: MIT License
    Operating System :: POSIX :: Linux
    Operating System :: Unix
    Operating System :: MacOS
    Operating System :: Microsoft :: Windows

zip_safe = False
packages = find_namespace:
python_requires = >=3.6
include_package_data = True
package_dir =
# Add here dependencies of your project (semicolon/line-separated)
install_requires =

where = src
exclude =

# Add here additional requirements for extra features, like:
# pdf = ReportLab>=1.2; RXP
# rest = docutils>=0.3; pack ==1.1, ==1.3
all = django; cookiecutter
# Add here test requirements (semicolon/line-separated)
testing =

# Add here console scripts like:
# console_scripts =
#     script_name = ${package}.module:function
# For example:
# console_scripts =
#     fibonacci = ${package}.skeleton:run
# And any other entry points, for example:
# pyscaffold.cli =
#     awesome = pyscaffoldext.awesome.extension:AwesomeExtension

# Options for py.test:
# Specify command line options as you would do when invoking py.test directly.
# e.g. --cov-report html (or xml) for html/xml output or --junitxml junit.xml
# in order to write a coverage file that can be read by Jenkins.
addopts =
    --cov my_project --cov-report term-missing
norecursedirs =
testpaths = tests
markers =
    slow: mark tests as slow (deselect with '-m "not slow"')

universal = 1

# Options for the devpi: PyPI server and packaging tool
# VCS export must be deactivated since we are using setuptools-scm
no-vcs = 1
formats =

# Some sane defaults for the code style checker flake8
max-line-length = 88
extend-ignore = E203, W503
# ^  Black-compatible
#    E203 and W503 have edge cases handled by black
exclude =

# PyScaffold's parameters when the project was created.
# This will be used when updating. Do not change!
version = 4.0
package = my_package
extensions =
namespace = ns1.ns2

You might also want to have a look on pyproject.toml for specifying dependencies required during the build:

requires = ["setuptools>=46.1.0", "setuptools_scm[toml]>=5", "wheel"]
build-backend = "setuptools.build_meta"

# See configuration details in
version_scheme = "no-guess-dev"

Please note PyScaffold will add some internal information to setup.cfg, we do that to make updates a little smarter.


To avoid splitting the configuration and build parameters among several files, PyScaffold uses the same file as setuptools (setup.cfg). Storing configuration in pyproject.toml is not supported. In the future, if the default build metadata location changes (as proposed by PEP 621), PyScaffold will follow the same pattern.

PyScaffold’s Own Configuration

PyScaffold also allows you to save your favourite configuration to a file that will be automatically read every time you run putup, this way you can avoid always retyping the same command line options.

The locations of the configuration files vary slightly across platforms, but in general the following rule applies:

  • Linux: $XDG_CONFIG_HOME/pyscaffold/default.cfg with fallback to ~/.config/pyscaffold/default.cfg

  • OSX: ~/Library/Preferences/pyscaffold/default.cfg

  • Windows(≥7): %APPDATA%\pyscaffold\pyscaffold\default.cfg

The file format resembles the setup.cfg generated automatically by PyScaffold, but with only the metadata and pyscaffold sections, for example:

author = John Doe
author-email =
license = MPL-2.0

extensions =

With this file in place, typing only:

$ putup myproj

will have the same effect as if you had typed:

$ putup --license MPL-2.0 --cirrus --pre-commit myproj


For the time being, only the following options are allowed in the config file:

  • metadata section: author, author-email and license

  • pyscaffold section: extensions (and associated opts)

Options associated with extensions are the ones prefixed by an extension name.

To prevent PyScaffold from reading an existing config file, you can pass the --no-config option in the CLI. You can also save the given options when creating a new project with the --save-config option. Finally, to read the configurations from a location other then the default, use the --config PATH option. See putup --help for more details.


Experimental Feature - We are still evaluating how this new and exciting feature will work, so its API (including file format and name) is not considered stable and might change between minor versions. As previously stated, if the configuration file for setuptools changes (e.g. with PEP 621), PyScaffold will follow that and change its own configuration.

This means that in future versions, PyScaffold will likely adopt a more pyproject.toml-style configuration (and as a consequence the file name and extension might change).