The Trac Configuration File

Trac is configured through the trac.ini file, located in the <projectenv>/conf directory. The trac.ini configuration file and its parent directory should be writable by the web server.

Trac monitors the timestamp of the file to trigger a complete environment reload and flush its caches when the timestamp changes. Most changes to the configuration will be reflected immediately, though changes to the [components] or [logging] sections will require restarting the web server. You may also need to restart the web server after creating a global configuration file when none was previously present.

Global Configuration

Configuration can be shared among environments using one or more global configuration files. Options in the global configuration will be merged with the environment-specific options, with local options overriding global options. The global configuration file is specified as follows:

file = /path/to/global/trac.ini

Multiple files can be specified using a comma-separated list.

Note that you can also specify a global option file when creating a new project, by adding the option --inherit=/path/to/global/trac.ini to trac-admin's initenv command. If you do not do this but nevertheless intend to use a global option file with your new environment, you will have to go through the newly generated conf/trac.ini file and delete the entries that will otherwise override those set in the global file.

There are two more entries in the [inherit] section, templates_dir for sharing global templates and plugins_dir, for sharing plugins. Those entries can themselves be specified in the shared configuration file, and in fact, configuration files can even be chained if you specify another [inherit] file there.

Note that the templates found in the templates/ directory of the TracEnvironment have precedence over those found in [inherit] templates_dir. In turn, the latter have precedence over the installed templates, so be careful about what you put there. Notably, if you override a default template, refresh your modifications when you upgrade to a new version of Trac. The preferred way to perform TracInterfaceCustomization is still to write a custom plugin doing an appropriate ITemplateStreamFilter transformation.

Reference for settings

This is a brief reference of available configuration options, and their default settings.

Documentation improvements should be discussed on the trac-dev mailing list or described in a ticket. Even better, submit a patch against the docstrings in the code.



List of email addresses that get notified of user changes, ie, new user, password change and delete user.

(no default)

Allow users to delete their own account.


Launch an initial Trac authentication setup.


Persistent sessions randomly get a new session cookie ID with likelihood in percent per work hour given here (zero equals to never) to decrease vulnerability of long-lasting sessions.


Realm to select relevant htdigest db entries

(no default)

Default hash type of new/updated passwords


A validation regular expression describing new account emails. Define constraints for a valid email address. A custom pattern can narrow or widen scope i.e. to accept UTF-8 characters.


Whether environment variable REMOTE_USER should get overwritten after processing login form input. Otherwise it will only be set, if unset at the time of authentication.


Force the user to change password when it's reset.


Length of the randomly-generated passwords created when resetting the password for an account.


Path relative to Trac environment or full host machine path to password file

(no default)

Realm to select relevant htdigest file entries

(no default)

Set to True, to switch login page style showing alternative actions in a single listing together.


Comma separated list of actions to notify of. Available actions 'new', 'change', 'delete'.

(no default)

Ordered list of password stores, queried in turn.

(no default)

Allow the user to be remembered across sessions without needing to re-authenticate. This is, user checks a "Remember Me" checkbox and, next time he visits the site, he'll be remembered.


Re-set passwords on successful authentication. This is most useful to move users to a new password store or enforce new store configuration (i.e. changed hash type), but should be disabled/unset otherwise.


A question to ask instead of the standard prompt, to which the value of register_basic_token is the answer. Setting to empty string (default value) keeps the standard prompt.

(no default)

A string required as input to pass verification.

(no default)

Ordered list of IAccountRegistrationInspector's to use for registration checks.


Whether account registration requires administrative approval to enable the account or not.


Set to False, if there is no email system setup.