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


Migration to Dovecot

Dovecot is one of the easiest IMAP servers to migrate to because of its very powerful configuration options. Dovecot can store email in both MBOX and MAILDIR formats making it compatible with most other mail storage formats. It is very flexible as to where it stores the email. Dovecot supports many methods for storing user data and password authentication. You can set it up to authenticate against multiple databases.

Migration involves several separate tasks. You either need to convert your data or make Dovecot read your existing data. Dovecot is very good at being compatible and configurable so that it is likely to read your existing mail folders and user and password configurations. Tasks for conversion include:

When migrating from one IMAP server to another, you should make sure that these are preserved:

Here's the more server-specific instructions:


By default UW-IMAP allows access to whole home directory, and many people have chosen to store their mails in mail/ directory. This usually means that IMAP clients have set "IMAP namespace" to "mail/", which doesn't work well with Dovecot, as Dovecot by default uses mail/ directory directly. So if IMAP namespace is kept as "mail/", Dovecot would try to access "~/mail/mail/" directory.

So, removing the prefix from IMAP clients would be the first step. Next problem is that subscribed mailboxes are listed as "mail/box" or "~/mail/box" or "~user/mail/box" in subscriptions file. You'd have to remove the mail/ directory part from all of these. The subscriptions file name is also different, UW-IMAP uses .mailboxlist while Dovecot uses .subscriptions.

Dovecot uses UW-IMAP compatible UID and message flag headers in mboxes, so that's not a problem.


default_mail_env = mbox:~/mail:INBOX=/var/mail/%u
# make sure mbox_locks are the same with all software that accesses your mboxes
mbox_locks = dotlock fcntl

If you want to make a transparent migration to Dovecot without having to change the configuration on hundreds of client systems, you will need a slightly different configuration.


Only concerns Dovecot 0.99.x versions, 1.0-releases use them:

Every folder on a system using UW-IMAP has a system message in the top with the subject "DON'T DELETE THIS MESSAGE -- FOLDER INTERNAL DATA". This system message has information about the folder and its state. Dovecot 0.99.x does not use these system messages to anything so you can delete them without any problems - unless you have users using Pine together with an IMAP or POP3 mailclient.


By default Dovecot generates POP3 UIDs differently than UW-IMAP. If you want to preserve them, with 0.99.x you'll have to [ patch Dovecot]. With 1.0-tests you can use:

pop3_uidl_format = %08Xv%08Xu

Note: Confirm that old and new UIDLs match. 0.99.x may not have the same uidl as UW-IMAP. Version 1.0 appears to be the same as UW-IMAP. Check with:

telnet localhost 110
user test
pass test


VIMAP or [ Virtual Imap] was a patched version of WU-IMAP that was modified to work with [ Linuxconf's] virtual email configuration. The project doesn't seem to have much life and [ Patrick Hall] who wrote the patch is thrilled that Dovecot can now be configured to be fully compatible. Details of how to do this are described in the [wiki:VirtualUsers Virtual Users] section.


Courier by default uses "INBOX." as private IMAP namespace, so it has exactly the same problems as described with UW-IMAP above. Again, if you want the migration to be transparent for IMAP clients see [wiki:Namespaces Namespaces] how to get namespaces to be Courier-compatible.

See also the [ courier2dovecot] script by Arto Bendiken.


# normal home directories
default_mail_env = maildir:~/Maildir
# for virtual users
default_mail_env = maildir:~/

For POP3 UIDL compatibility, use one of:

# Courier version 0 (using maildir filenames)
pop3_uidl_format = %f
# Courier version 1 (UID)
pop3_uidl_format = %u
# Courier version 2  (UIDVALIDITY and UID - you most likely want this)
pop3_uidl_format = %v-%u


See [ cyrus2courier], it's Dovecot-compatible. Also mirrored at [].

For POP3 UIDL compatibility, use one of:

#  Cyrus (old format - up to v2.1.3)
pop3_uidl_format = %u
#  Cyrus (new format - v2.1.4 and above)
pop3_uidl_format = %v.%u

See [] for an alternative migration script (in Python) for Cyrus IMAPd 2.2, which will preserve delivery timestamps and read status.

Also, there exists a script called IMAPSync [] which does a nice job of syncing from one IMAP server to another without caring what IMAP server is runing on either end. It has been effective for various migrations for us so far, and worked well for migrating from a Cyrus IMAP server to Dovecot. Here's an example of how you might run the script for a single user:

imapsync --host1 --authmech1 LOGIN --user1 --password1 secret --host2 localhost --authmech2 LOGIN --user2 --password2 secret --syncinternaldates

This is quite easy to script for a number of users, assuming you have their passwords. Even if you do not, the script also supports logging in as an admin user that has the ability to copy message for sub users, and a variety of other authentication options.

Other POP3 servers

Some POP3 servers generate the X-UIDL header. To use this header when available and ease migration, use:

# Use X-UIDL header if available
pop3_reuse_xuidl = yes

Different POP3 servers generate UIDs differently. If you want to preserve them to avoid users downloading their mails twice, you'll need to figure out how the server generates the UID and patch Dovecot accordingly to do the same.

Here is a list of POP3 servers and how they generate their UIDs. Please update if you know more:

Converting Mailbox Formats

Converting from MBX to MBOX

If you are using WU-IMAP and using the MBX format you will need to convert it to MBOX format. The conversion process isn't pretty, but here's a script that works. You will need to get and compile the mailutil program from the WU-IMAP web site.

# Written by Marc Perkel - public domain
# Usage mbx-convert <filename>
# This code assumes a user named "marc". Change to any real user on your system.
# Yes - it look bizzare - but it gets the job done

# First copy to users home dir and make the user the owner
cp "$*" /home/marc/in
chown marc:marc /home/marc/in

# Run mailutil to convert as the user other than root 
# mailutil requires this
su - marc -c "/usr/bin/mailutil copy in \#driver.mbx/out"

# cat instead of copy preserves the original owner and permissions
cat /home/marc/out > "$*"

# cleanup
rm /home/marc/in
rm /home/marc/out

Make a copy of some folders and test it first. Once you are satisfied that it works then:

Converting from MBOX to Maildir

[ mb2md] is a script which can convert the files for you.

Check also the User-Contributed Maildir Support section [ here] for more choices.

Example (user's mail in ~someuser/mail and inbox in /var/mail/someuser):

cd ~someuser -s mail -R -m -d /var/mail/incoming/someuser
mv mail mail.old

Now the mail will be in ~someuser/Maildir

If you are coming from uw-imap, you also need to do:

cp -p .mailboxlist Maildir/subscriptions

Note that maildir handles subdirectories differently. You need to replace "/" with "." in the subscriptions file:

sed "s/\//\./" subscriptions >
mv subscriptions

Don't forget to update "default_mail_env" in dovecot.conf (as needed)

Converting from Maildir to MBOX

This is especially helpful if you want to archive your mail to a single file for storage on a CD, a PC, etc. But it can also be helpful if you want to use MBOX with dovecot.

Use the formail program that comes with [ procmail]. Here is a simple script showing how this works. Change to the user's home directory (the parent of Maildir) and run the script with two arguments: the mailbox name, and the output mbox filename.

if (($outputfile eq '') || ($dir eq '') || (!stat("Maildir/$dir")))
{ die "./ mailbox outputfile\n"; }

 if (($name ne '.') && ($name ne '..'))
  system("cat Maildir/$dir/cur/$name | formail >> $outputfile");