Configuration Reference#

towncrier has many knobs and switches you can use, to customize it to your project’s needs. The setup in the Quick Start doesn’t touch on many, but this document will detail each of these options for you!

For how to perform common customization tasks, see Customization.


All configuration for towncrier sits inside pyproject.toml, under the tool.towncrier namespace. Please see for how to write TOML.

Top level keys#

  • directory – If you are not storing your news fragments in your Python package, or aren’t using Python, this is the path to where your newsfragments will be put.

  • filename – The filename of your news file. NEWS.rst by default.

  • package – The package name of your project. (Python projects only)

  • package_dir – The folder your package lives. ./ by default, some projects might need to use src. (Python projects only)

  • template – Path to an alternate template for generating the news file, if you have one.

  • start_string – The magic string that towncrier looks for when considering where the release notes should start. .. towncrier release notes start by default.

  • title_format – A format string for the title of your project. {name} {version} ({project_date}) by default.

  • issue_format – A format string for rendering the issue/ticket number in newsfiles. #{issue} by default.

  • underlines – The characters used for underlining headers. ["=", "-", "~"] by default.

Custom fragment types#

towncrier allows defining custom fragment types. Custom fragment types will be used instead towncrier default ones, they are not combined.

There are two ways to add custom fragment types.

Defining Custom Fragment Types With a TOML Mapping#

Users can configure each of their own custom fragment types by adding tables to the pyproject.toml named [tool.towncrier.fragment.<a custom fragment type>].

These tables may include the following optional keys:

  • name: The description of the fragment type, as it must be included in the news file. If omitted, it defaults to its fragment type, but capitalized.

  • showcontent: Whether if the fragment contents should be included in the news file. If omitted, it defaults to true

For example, if you want your custom fragment types to be ["feat", "fix", "chore",] and you want all of them to use the default configuration except "chore" you can do it as follows:



name = "Other Tasks"
showcontent = false


Since TOML mappings aren’t ordered, the sections are always rendered alphabetically.

Defining Custom Fragment Types With an Array of TOML Tables#

Users can create their own custom fragment types by adding an array of tables to the pyproject.toml named [[tool.towncrier.type]].

If you use this way to configure custom fragment types, please note that fragment_types must be empty or not provided.

Each custom type ([[tool.towncrier.type]]) has the following mandatory keys:

  • directory: The type / category of the fragment.

  • name: The description of the fragment type, as it must be included in the news file.

  • showcontent: Whether if the fragment contents should be included in the news file.

For example:

directory = "deprecation"
name = "Deprecations"
showcontent = true

directory = "chore"
name = "Other Tasks"
showcontent = false

All Options#

towncrier has the following global options, which can be specified in the toml file:

package = ""
package_dir = "."
single_file = true  # if false, filename is formatted like `title_format`.
filename = "NEWS.rst"
directory = "directory/of/news/fragments"
version = "1.2.3"  # project version if maintained separately
name = "arbitrary project name"
template = "path/to/template.rst"
start_string = "Text used to detect where to add the generated content in the middle of a file. Generated content added after this text. Newline auto added."
title_format = "{name} {version} ({project_date})"  # or false if template includes title
issue_format = "format string for {issue} (issue is the first part of fragment name)"
underlines = "=-~"
wrap = false  # Wrap text to 79 characters
all_bullets = true  # make all fragments bullet points
orphan_prefix = "+"   # Prefix for orphan news fragment files, set to "" to disable.

If single_file is set to true or unspecified, all changes will be written to a single fixed newsfile, whose name is literally fixed as the filename option. In each run of towncrier build, content of new changes will append at the top of old content, and after start_string if the start_string already appears in the newsfile. If the corresponding top_line, which is formatted as the option ‘title_format’, already exists in newsfile, ValueError will be raised to remind you “already produced newsfiles for this version”.

If single_file is set to false instead, each versioned towncrier build will generate a separate newsfile, whose name is formatted as the pattern given by option filename. For example, if filename="{version}-notes.rst", then the release note with version “7.8.9” will be written to the file “7.8.9-notes.rst”. If the newsfile already exists, its content will be overwritten with new release note, without throwing a ValueError warning.

If title_format is unspecified or an empty string, the default format will be used. If set to false, no title will be created. This can be useful if the specified template creates the title itself.