Skip to content

Configuration Reference

Ghjuvan Lacambre edited this page Aug 20, 2019 · 18 revisions

All default config options should be found in the file of astroid.

This page is a work in progress to document all config options available in Astroid. Feel free to contribute.


This page describes every configation option for astroid.

Each option is an entry in the astroid config file (typically $HOME/.config/astroid/config see also Astroid-setup)

We describe the options in a dotted notation like for example astroid.config.version. In the actual file this means the option can be found as follows.

  "astroid" : {
	  "config" : {
		  "version" : "9"

That is, follow the "path" to the "version" option by going via "astroid" and "config".

The examples given is what you would write on the line where you find the option, so for the above an example would look like:

"version" : "9"

This notation saves us from continuously writing out the whole JSON tree and makes the document more readable.

Options are always written between double quotes, but do have certain types. Possible types:

  • string : "A line of text"
  • file-path : a path to a file in the filesystem
  • directory-path : a path to a directory in the filesystem
  • rgb hex : a css-like color specification in #rrggbb format
  • boolean : "true" or "false"
  • integer : a number
  • float : floating point number (ex. 0.5)
  • list : a, comma, separated, list

[comment]: # detail value restrictions of the types


Undocumented options

  • log.level
  • log.syslog
  • log.stdout


Type    : integer
Default : none, generated by astroid on startup

The version number of the config in use. This setting is used by astroid internally to help you with upgrading to newer astroid version which introduce new configuration items. This setting is normally not changed by the user.


Type    : boolean
Default : false

This option can be helpful while you are configuring your astroid setup, which may be a bit of work. When set to true, this option does a dry-run on sending messages, that is the program does not actually send the messages, but otherwise behaves as if it was normally configured.


Type    : filepath
Default : Depends on the [notmuch] configuration file location

This should point to your notmuch configuration file path. Astroid reads some settings from your notmuch configuration and uses them. If the path starts with a tilde it will be expanded to the current user's home directory. This setting is typically automatically configured when you first start using astroid (see: Astroid-setup).

If the NOTMUCH_CONFIG environment variable is set, it will be honored over this configuration option.


"notmuch_config": "\/home\/alice\/.notmuch-config"

For file paths in the config, we need to escape the / character by preceding it with a backslash.


Type    : Integer
Default : 0

Astroid's interface will display hints on several occasions to guide the user through certain actions (e.g. how to edit a draft email or how to cancel an email being sent). These hints are assigned a level.

This option enables you to filter out some hints by level. The higher you set this option, the less hints will be displayed.

By default, it is 0, i.e. only hints for which Astroid has assigned a level above 0 will be displayed.


To ensure that all hints are displayed, set this to -1.

"level": "-1"

[comment]: # TODO: make inventory of hints and table them up here, grouped by level



Type: string
Default: default

Set font of embedded terminal. Values are parsed using Pango and should conform to that format.

default or empty uses default monospace font (same as thread-index).


Type: integer
Default: 10

Sets the height of the embedded terminal.

Thread index options

When astroid opens, you typically see a list of threads first; the thread-index. The options in this section are applicable to these thread-index screen.


Type    : integer
Default : 6

When scrolling though an index, for example with the default key "J" this is the amount of rows astroid scrolls. So, larger values make you jump faster through the index and smaller values make you jump slower.

A value smaller than 2 really makes no sense, but 1 will still work. Anything smaller or even negative will disable the jump.


Type    : string
Default : "newest"

This option determines how the threads in the index are sorted for display. The possible values for this option are:

  1. "newest" (default) : newest threads first (based on last msg?)
  2. "oldest" : oldest threads first (based on last msg?)
  3. "messageid" : sort by descending(?) messageid
  4. "unsorted" : no attempt is made by astroid to sort the threads


Type    : integer
Default : 250

This option is unused at the moment.


Type    : string
Default : "default"

Either the text "default" or a so called Pango FontDescription describing what font to use in the index.

A bit more information on a Pango FontDescription can be found at:


Type    : integer
Default : 2

The amount of vertical space, in pixels(?) to leave as spacing between each thread in the index.


Type    : integer
Default : 10

The amount of characters to reserve for the date column


Type    : integer
Default : 4

The amount of characters to reserve for the message count column


Type    : integer
Default : 20

The amount of characters to reserve for the authors column


Type    : rgb hex
Default : #807d74

A specification of the foreground color of subjects in the thread-index screen.


Type    : rgb hex
Default : #000000

Specification of the foreground color of the subjects when the thread line has the focus in the thread-index screen.


Type    : rgb hex
Default : ""

Specification of the background color in the thread-index screen. Empty mean that the GTK theme configurationb decides what to do with a selection.


Type    : integer
Default : 80

The amount of characters to reserver for displaying the tags.


Type    : rgb hex
Default : #e5e5e5

Tags get assigned a color out of a range automatically based on their name. This option value determines the upper value of the colors in the range.


Type    : rgb hex
Default : #333333

Tags get assigned a color out of a range automatically based on their name. This option value determines the lower value of the colors in the range.


Type    : float
Default : 0.5

This fraction determines how transparent tags are displayed and ranges from 0 to 1. A value of 0 would mean that the tags are totally transparent and a value of 1 means totally oblique.

The option is called alpha because a common technique to get things to display with the illusion of transparency is called Alpha compositing

If it were me, i'd have called it transparency


Type    : list
Default : attachment,flagged,unread

A list of tags which you do not want to see in the tag display. Typically these are tags for which another visual clue exists already. For example, the attachment icon shows that there is an attachment, so the tag is redundant and is hidden by default.

Thread view

When drilling down on a thread a screen opens where you can view a summary of the individual messages in a thread; the thread view. The options in this section apply to all of these thread-view screens.


Type    : boolean
Default : false

If a message has multiple parts and one of them is html, you can choose to have that part opened by an external application (typically your internet browser) or have astroid render it inside the thread-view.


Type    : string
Default : "xdg-open"

If a message contains links to external content, use the value of this option to spawn an external program to open such links. The link is taken from the message and appended to the configured string at the end.


Type    : directory-path
Default : "~"

This option configures the default directory where to save messages.


Type    : boolean
Default : false

If this option is set to true the messages in the thread-view are indented with respect to their parent if a message is a reply to it thus forming a 'tree' of the messages. This might make it easier to navigate long threads.


Type    : boolean
Default : true

Astroid has the option to prettify certain pieces of code in messages. This options is the main switch to enable this feature. See the options below on how to fine-tune it.

For the code prettifying astroid makes out calls to an external site which runs


Type    : list
Default : ""

Only prettify messages which are tagged with a tag contained in this option. If the option is left empty, prettifying is done for all messages, assuming the code_prettify_enable option has been set to true


Type    : string
Default : "```"

The contents of this option is used as the trigger for astroid where to start prettifying things.


Type    : boolean
Default : true

Regardless of the prettify_for_tags setting you can enable prettifying code when a mail is a patch. The definition that astroid uses to determine if a message is a patch has 2 criteria:

  1. the subject matches the regular expression \\[PATCH.*\\]
  2. the subject does NOT start with RE:, likely making the message a reply.

If those 2 conditions are met astroid considers the message a patch and if this option is set to true will enable prettifying for that message.


Type    : boolean
Default : true

Gravatar is a system which maps email addresses to images, or avatars, with the intent to show next to the email-adres. This mapping is provided by the site If you set this option to true, astroid will send an email-address to and retrieve an avatar-image stored there for the owner of that email-address.


Type    : float
Default : .5

When viewing a message, the tag unread will be removed, because the message has been viewed. This option configures the amount of time astroid will wait before doing that. The idea is that you can see that the message was unread while viewing the message.


Type    : boolean
Default : true

In the thread view messages have two states, they are either collapsed (showing just a summary) or expanded (showing the whole message). This toggle makes messages that are flagged (i.e. have that tag) be expanded by default.


  • thread_view.preferred_type: either plain (default) or html.
  • thread_view.preferred_html_only: bool, (default: false), show html part if there are no other preferred parts. (requries thread_view.open_html_part_external == false).
  • thread_view.allow_remote_when_encrypted, bool (default: false) allow remote images when any one message is encrypted (#499)


General options, surprisingly all about how time and dates should be displayed on the screen.


Type    : string
Default : "local"

This option specifies how time should be displayed and can have 4 values:

  1. "local" (default) : the locale on the machine determines how to show time
  2. "12h" : use a 12-hour notation
  3. "24h" : use a 24-hour notation
  4. "year": use the format described in general.time.same_year and general.time.diff_year.


Type    : string
Default : "%b %-e"

If messages are from the same year as the current date, this format is used to display the date of the message.


Type    : string
Default : "%x"

If messages are from different year than the current date, this format is used to display the date of the message.


Type: bool Default: true

Log to stdout.


Type: bool Default: false

Log to syslog.


Type: string Default: debug (Debug build), info (Release build) Possible values: trace, debug, info, warning, error, fatal


Options related to editing and composing messages.


Type    : string
Default : "gvim -geom 10x10 --servername %2 --socketid %3 -f -c 'set ft=mail' '+set fileencoding=utf-8' '+set ff=unix' '+set enc=utf-8' '+set fo+=w' %1"

This option allows you to specify the exact command line to use for editing messages. See Customizing-editor for all the details.


Type    : boolean
Default : true

Set this flag to true when the editor is external, the instructs astroid that editing should not be embedded in its own windows and just the file argument is passed through to the editor.cmd option.


Type    : string
Default : "utf-8"

Which encoding does the editor use.


Type    : string
Default : "marked"

Markdown processor used to generate HTML MIME parts. By default set to marked. The processor must accept markdown text on stdin and output HTML on stdout. A separate signature file is used for the markdown part.


Type    : directory-path
Default : "~"

When loading or saving attachment, use this directory path by default.


Type    : boolean
Default : true

If a forced quit is detected by astroid, it makes an attempt to save unsent messages to a draft file if this option is set to true


Type    : list
Default : attach

A list of words that astroid checks for in composed messages before sending. If any of these words are in the message and there is no attachment it may be likely that you have forgotten your attachments. Astroid will show you a warning.


Options related to the contents of a mail message and its headers.


Type    : string
Default : "Excerpts from %1's message of %2:"

When replying to a message, this line will be inserted before the message quoted. The placeholder %1 is replace by the authorname of the message replied to and %2 is replaced by the date of the message.


Type    : boolean
Default : true

When replying to a mailinglist, the reply will go to the sender of the message instead of to the list, if this option is set to true


Type    : string
Default : "Forwarding %1's message of %2:"

Similar to mail.reply.quote_line but for forwarding messages.


Type    : string
Default : "inline"

Should messages be forwarded inline or attachment.


Type    : list
Default : sent

Astroid assigns these tags to messages it sends. The special value * assigns all the tags that the message being replied to has. You can filter tags by prefixing them with -. For example, sent,*,-attachment applies the tag sent and all tags the message being replied to has except attachment.


Type    : string
Default : ""

For all mail message a so called message id header is created. When this option is filled, the value is used as the domain part in the message id header. The default, that is when the option has no value, is to take the local hostname.


Type    : string
Default : ""

In addition to mail.message_id.fqdn there is also a user part in that message id header. You can specify here what you want in that header. The default is astroid

There is a section on why these two options can be useful in Customizing-editor


Type    : string
Default : "default"

Another header that is put into mail messages is the "User-Agent" header which gives receivers some information about which program was used to assemble the message. The contents of this head can be specified here. When set to the empty string, the "User-Agent" header will be omitted from outgoing messages.

If you specify default, something like this will be sent:

astroid/v0.9.1-47-g44fddc99 (

which is astroid along with its version and git revision.


Type    : integer
Default : 2

The number of seconds astroid will wait after you sent a message, before actually doing so. This gives you a chance to cancel it if needed. If you specify 0 then the message will be sent immediately


Type    : bool
Default : false

The mail composition page will automatically be closed after the message has been successfully sent if this is set tot True.


Type    : bool
Default : false

format=flowed will be added to the Content-Type header. This indicates that the message content can be re-flowed by the receiver or when quoting the message. The editor you are using should be configured accordingly - otherwise the behavior can result in somewhat weird formatting on the receiver end (#446,f=f).

For Vim you could use something like this if you set format=flowed:

 " format=flowed 
au FileType mail setlocal tw=72 
au FileType mail setlocal fo+=q 
au FileType mail setlocal comments+=nb:>

" Rewrap paragraph using <S-q>
map <silent> <S-q> {gq}<Bar>:echo "Rewrapped paragraph"<CR>


Astroid has some support for cryptographically signing and/or encrypting your messages. Note that this is different from a mail signature, which is just a piece of text added to your message, while a cryptographic signature signals that you can prove to the receiver of the message that you actually are who you say you are.

Astroid interfaces with GNUpg so these options only make sense if you are using that.


Type    : file-path
Default : "gpg2"

The path to your GNUpg executable, or just the name of the program if it is in your PATH.


Type    : boolean
Default : true

This option determines if gpg, the program that does the encryption and signing, sets the value always_trust in its context.

When it does, key validation is skipped and keys are assumed to be always valid and as such can be used in astroid.

See the gnupg documentation for the details.


Type    : boolean
Default : true

This option allows you to turn off both encryption and decryption of GPG encrypted messages. This can be used to ensure against attacks like EFAIL (although we do not think that Astroid is vulnerable to the exploit).

Saved searches

As an interface to notmuch handling searches is a very common option in astroid. These are the options related to saving those searches for repeated use.


Type    : boolean
Default : false

Determines if astroid show the saved searches when starting up. Instead of the first startup query it shows the screen with your saved search and the configured search history.

Note that if you set this to false and you have no startup queries configured, astroid will start up with a blank screen, which may be confusing, but it will be fully functional.


Type    : boolean
Default : true

Save a list of performed searches when set to true


Type    : integer
Default : 15

How many searches should we show in the list. If you set this, show them all.


Type    : integer
Default : 1000

Place an upper limit on how many searches astroid should save.


You can have multiple account definitions in astroid. Each account gets a section in the config file under its name. In the description of the options this is represented by [accountname]

The defaults listed for these options are for the charlie demo account created on first use of astroid. You will need to change the accounts section to have your accounts listed.


Type    : string
Default : "Charlie Root"

The name which you want to associate with the account, it will be used in the from address.


Type    : string
Default : "root@localhost"

The email-address of the account, also used in the from address.


Type    : string
Default : ""

Which gpg key is associated with this account. By specifying this, astroid can sign and encrypt your messages.


Type    : boolean
Default : false

Should astroid always sign your messages?


Type    : string
Default : "msmtp -i -t"

What is the exact commandline to use when sending a message. This is important to get right. See also Astroid-setup


Type    : boolean
Default : true

Is this the default account? This is only relevant if there is more than one account configured.


Type    : boolean
Default : true

Should astroid save sent messages somewhere? You probably want this set to true and configure the next option.

Another option is to configure your MTA (msmtp, postfix etc.) to do some magic to messages being sent out. For example, postfix has a always_bcc option which takes an email address; it will send a copy of all outgoing messages to that address.


Type    : directory-path
Default : /home/root/Mail/sent/cur/

This is the directory where astroid will save the sent messages to. Note that the end of the directory ends here in /cur/ which is a Maildir specific thing.


Type    : list
Default : sent

The special value * assigns all the tags that the message being replied to has. You can filter tags by prefixing them with -. For example, foo,*,-attachment applies the tag foo and all tags the message being replied to has except attachment.


Type    : directory-path
Default : /home/root/Mail/drafts/

Similar to save_sent_to this is the path where draft messages are saved. Note that here the end does not contain /cur/ which in many cases has the effect that programs like mbsync will not sync your draft messages back to an IMAP server for example.


Type    : file-path
Default : ""

The location of the file which holds the message signature associated with this account.


Type    : file-path
Default : ""

The location of the file which holds the mardown version of the message signature associated with this account. If no markdown signature file is specified, the HTML part will will not have a signature unless it is attached. Only signature_file will have effect if signature_attach is true.


Type    : boolean
Default : true

Should the signature be inserted by default by astroid?


Type    : boolean
Default : false

Signatures can be inserted into the message as plain contents or attached to the message as a separate part. It's fairly common to not attach a signature (note: this is not a cryptographical signature as mentioned before) but to just append it to the message.


Type    : boolean
Default : false

A toggle that decides how a signature is added to a message. If the value is "true" then the signature will be separate from the message content and have the defacto standard signature separator -- on its own line between the message and the signature. If the value is "false" then the signature will be appended to the message without separator line. The advantage of the separator line is that many mail programs use it to show the message and the signature in a different way, or hide it entirely

This option is only relevant for inline signatures. If you have configured astroid to have your signature as attachment, this option has no effect


A notmuch query used to select this account as sender when replying or forwarding, if the original message matches the specified query. Blank means no query. If no query is specified, first any of your account emails that are present in any of the From, To, Cc, or Bcc fields are used. If none matches, the default account is used.


Options which don't fit under any of the other sections.


Type    : integer
Default : 60

Astroid can poll the mail store for new and changed messages automatically. This options specifies the amount of seconds after which astroid repeats this. Polling means that a script in the config directory is executed, so you will have to specify there what is needed in your situation.


Type    : bool
Default : false

Will cause all thread-indexes to always be completely refreshed. Useful for detecting deleted threads. Will be slow. Default behavior only updates changed threads and messages, but does not delete threads that have been completely deleted.


Type    : string
Default : "xdg-open"

When opening attachment, this command is executed. The filename of the attachment is appended as an argument.


Type    : string
Default : see below

The section startup.queries contains lines in the form:

"NAME" : "...notmuch search term or query spec..."

separated by comma's. Each NAME gets a tab in astroid and the query specified is executed in it, giving a list of threads as found by notmuch


"startup": {
        "queries": {
            "INBOX": "tag:unread and not tag:deleted and not tag:muted",
            "TODO": "tag:flagged",
            "Drafts": "tag:draft"
Clone this wiki locally
You can’t perform that action at this time.