Command Line Reference#

The following options can be passed to all of the commands that explained below:

--config FILE_PATH#

Pass a custom config file at FILE_PATH.

Default: towncrier.toml or pyproject.toml file. If both files exist, the first will take precedence

--dir PATH#

Build fragment in PATH.

Default: current directory.

towncrier build#

Build the combined news file from news fragments. build is also assumed if no command is passed.


Only render news fragments to standard output. Don’t write to files, don’t check versions. Only renders the news fragments without the surrounding template.

--name NAME#

Use NAME as project name in the news file. Can be configured.

--version VERSION#

Use VERSION in the rendered news file. Can be configured or guessed (default).

--date DATE#

The date in ISO format to use in the news file.

Default: today’s date


Do not ask for confirmations. Useful for automated tasks.

towncrier create#

Create a news fragment in the directory that towncrier is configured to look for fragments:

$ towncrier create 123.bugfix.rst

towncrier create will enforce that the passed type (e.g. bugfix) is valid.

--content, -c CONTENT#

A string to use for content. Default: an instructive placeholder.


Create file and start $EDITOR to edit it right away.`

towncrier check#

To check if a feature branch adds at least one news fragment, run:

$ towncrier check

The check is automatically skipped when the main news file is modified inside the branch as this signals a release branch that is expected to not have news fragments.

By default, towncrier compares the current branch against origin/main (and falls back to origin/master with a warning if it exists, for now).

--compare-with REMOTE-BRANCH#

Use REMOTE-BRANCH instead of origin/main:

$ towncrier check --compare-with origin/trunk