This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.

Mail location

There are three different places where the mail location is looked up from:

  1. mail_location setting in dovecot.conf is used if nothing else overrides it.

  2. mail userdb field overrides mail_location setting.

  3. location setting inside namespaces overrides everything. Usually this should be used only for public and shared namespaces.


By default the mail_location setting is empty, which means that Dovecot attempts to locate automatically where your mails are. This is done by looking, in order, at:

For autodetection to work, one of the above locations has to be populated; when autodetection is active, Dovecot will not attempt to create a mail folder. Note that .imap is a directory, and inbox and mbox are files.

It's usually a good idea to explicitly specify where the mails are, even if the autodetection happens to work, in particular to benefit from auto-creation of the folder for new users.

Mailbox autocreation

Dovecot in the 1.x era created mailboxes automatically regardless of whether mail_location was set. In 2.x autocreation only gets triggered if mail_location is correctly set. You'll see something like this if you enable debug logging:

Debug: Namespace : /home/user/Mail doesn't exist yet, using default permissions
Debug: Namespace : Using permissions from /home/user/Mail: mode=0700 gid=default

and a Mail/.imap directory will be present once that process has concluded. This is the easiest way to ensure a freshly created user is correctly set up for access via Dovecot.


The format of the mailbox location specification is as follows:



You can use several variables in the mail_location setting. See Variables for a full list, but the most commonly used ones are:

Typical settings

Typically with Maildir it would be set to:

mail_location = maildir:~/Maildir

with mbox:

mail_location = mbox:~/mail:INBOX=/var/mail/%u

or if you'd like to use the dbox format:

# single-dbox
mail_location = sdbox:~/dbox


# multi-dbox
mail_location = mdbox:~/mdbox

Use only absolute paths. Even if relative paths would appear to work, they might just as well break some day.

Directory hashing

You can use two different kinds of hashes in variables:

Index files

Index files are by default stored under the same directory as mails. With maildir they are stored in the actual maildirs, with mbox they are stored under .imap/ directory. You may want to change the index file location if you're using NFS or if you're setting up shared mailboxes.

You can change the index file location by adding :INDEX=<path> to mail_location. For example:

mail_location = maildir:~/Maildir:INDEX=/var/indexes/%u

The index directories are created automatically, but note that it requires that Dovecot has actually access to create the directories. Either make sure that the index root directory (/var/indexes in the above example) is writable to the logged in user, or create the user's directory with proper permissions before the user logs in.

If you really want to, you can also disable the index files completely by appending :INDEX=MEMORY.

Private index files (v2.2+)

Since v2.2 the recommended way to enable private flags for shared mailboxes is to create private indexes with :INDEXPVT=<path>. See SharedMailboxes/Public for more information.

INBOX path

INBOX path can be specified to exist elsewhere than the rest of the mailboxes, for example:

mail_location = mbox:~/mail:INBOX=/var/mail/%u
mail_location = maildir:~/Maildir:INBOX=~/Maildir/.INBOX

Note that it's still not possible to mix maildir and mbox formats this way. You need to use namespaces for that.

Homeless users

Having a home directory for users is highly recommended. The Pigeonhole Sieve plugin already requires a home directory to work, and it probably won't be the last feature to require a home. See VirtualUsers#homedirs for more reasons why it's a good idea, and how to give Dovecot a home directory even if you don't have a "real home directory".

If you really don't want to set any home directory, you can use something like:

mail_location = maildir:/home/%u/Maildir 

Per-user mail locations

It's possible to override the default mail_location for specific users by making the user database return mail extra field. See the user database page for the specific userdb you're using for more information how to do this. Below are however a couple of examples.

Note that %h doesn't work in the userdb queries or templates. ~/ gets expanded later, so use it instead.

Note also that since location specified within a namespace overrides mail_location setting, in case you specified that parameter, you'll have to override in in the user database, specifying namespace/inbox/location extra field instead of mail.


user_query = SELECT home, uid, gid, mail FROM users WHERE user = '%u' 


user_attrs = homeDirectory=home, uidNumber=uid, gidNumber=gid, mailLocation=mail



Mixing mbox and maildir

It's possible to use both mboxes and maildirs for the same user by configuring multiple namespaces. See Namespaces.

Having both mboxes and maildirs mixed within the same namespace isn't currently supported.

Custom mailbox location detection

Dovecot by default detects the mailboxes in this order:

  1. maildir: ~/Maildir
  2. mbox: ~/mail, and /var/mail/%u if it exists
  3. mbox: ~/Mail, and /var/mail/%u if it exists

If you need something else, you can override the mail_executable setting to run a script, which sets the MAIL environment properly. For example:


if [ -d $HOME/.maildir ]; then
  export MAIL=maildir:$HOME/.maildir
  export MAIL=mbox:$HOME/mail:INBOX=/var/mail/$USER

exec "$@"

Custom namespace location

If you need to override namespace's location, first give it a name ("inbox" below):

namespace inbox {

Then in the script use:


# do the lookup here

export USERDB_KEYS="$USERDB_KEYS namespace/inbox/location"
exec env "NAMESPACE/INBOX/LOCATION=$location" "$@"