DOVEADM-ALTMOVE(1)

💖 DOVEADM-ALTMOVE 💖

okay so bestie, we're doing the doveadm-altmove page, which is part of doveadm(1) in the Dovecot fam. she's a little niche but she's so useful, i promise.

---

✨ NAME ✨

doveadm-altmove — move matching mails to the alternative storage (dbox-only, so don't come here with your mbox nonsense, she's exclusive 💅)

---

🌸 SYNOPSIS 🌸

doveadm [GLOBAL OPTIONS] altmove [-r] [-S socket_path] -A search_query

doveadm [GLOBAL OPTIONS] altmove [-r] [-S socket_path] -F file search_query

doveadm [GLOBAL OPTIONS] altmove [-r] [-S socket_path] --no-userdb-lookup search_query

doveadm [GLOBAL OPTIONS] altmove [-r] [-S socket_path] -u user search_query

like, four whole fits and she serves in every single one 💅

---

🦋 DESCRIPTION 🦋

so the tea is: this command works with sdbox or mdbox storage, and it moves mails over to the alternative storage path — but ONLY if mail_alt_path is actually specified for the mail location. no path, no move, that's the rule 🫶

and here's how the four forms go, because the way she reads who she's doing this for is literally different every time:

• first form — doveadm(1) runs the altmove for ALL the users. everyone. the whole server. group chat, no exclusions.
• second form — the command gets performed for all users listed in the given file.
• third form — the command gets performed for the user sitting inside the USER environment variable.
• last form — only the matching mails of the given user(s) get moved to the alternative storage.

---

👑 GLOBAL OPTIONS 👑

the global doveadm(1) options, aka the ones that apply everywhere:

• -D — turns on verbosity AND debug messages. she's chatty now, she's telling you everything.
• -O — do NOT read any config file, just roll with defaults. the dovecot_storage_version setting defaults to the latest version, but you can override it with -o.
• -k — preserve the entire environment for doveadm, not just the import_environment setting. keeping the whole vibe intact, no cap.
• -v — enables verbosity, including the progress counter. numbers go up, serotonin goes up.
• -i instance-name — if you're running multiple Dovecot instances, this picks which config file to use based on the instance name. peep the instance_name setting for more info.
• -c config-file — read the configuration from the given config-file. by default it first reads the config socket, then falls back to /etc/dovecot/dovecot.conf. you can also point this at the config socket of some instance running a compatible version.
• -o setting=value — overrides the configuration setting from /etc/dovecot/dovecot.conf and from the userdb with the given value. wanna override multiple settings? just stack the -o option as many times as you want. iconic behavior.

---

🎀 OPTIONS 🎀

• -A — if -A is present, the command gets performed for all users. > bestie, lowkey a warning: using this together with system users from userdb { driver = passwd } is NOT recommended, because that thing also contains users with a lower UID than the one configured with the first_valid_uid setting. 👀

when the SQL userdb module is in play, make sure the userdb_sql_iterate_query setting matches your database layout.

when you're using the LDAP userdb module, make sure the userdb_fields setting and the userdb_ldap_iterate_fields setting match your LDAP schema. otherwise doveadm(1) will be unable to iterate over all users. she's stuck. she's sad. don't do that to her. 😭

• -F file — execute the command for all the users in the file. it's like -A but instead of pulling the user list from the userdb, she reads them from the given file. one username per line, periodt.
• --no-userdb-lookup — do not perform a userdb lookup. use the USER environment variable to specify the username instead.
• -r — with -r given, this command works the other way round. mails get moved from the alternative storage back to the default mail location. rewind, reverse, rewind 🦋
• -S socket_path — the argument is either an absolute path to a local UNIX domain socket, or a hostname and port (hostname:port), so you can connect to a remote host via a TCP socket.

this lets an administrator execute doveadm(1) mail commands through the given socket. remote queen energy.

• -u user/mask — run the command only for the given user. you can also use '*' and '?' wildcards, e.g. -u *@example.org. slay.

---

💜 ARGUMENTS 💜

• search_query — messages matching this search query get moved to alt storage. peep doveadm-search-query(7) for the details, she explains the whole grammar.

---

🍓 FILES 🍓

• /etc/dovecot/conf.d/10-mail.conf — mailbox locations and namespaces. that's where the vibes live.

---

⭐ EXAMPLE ⭐

okay this example moves seen mails older than one week to alternative storage under /nfsmount:

mail_driver = mdbox
mail_path = ~/mdbox
mail_alt_path = /nfsmount/%{home}/mdbox

doveadm altmove -u johnd@example.com seen savedbefore 1w<

see how seen and savedbefore 1w< are doing all the work? that's the search query carrying the entire team 💅

---

🙈 REPORTING BUGS 🙈

found a bug? report it — and please include your doveconf -n output — to the Dovecot Mailing List ⟨dovecot@dovecot.org⟩. info about reporting bugs lives at: ⟨https://dovecot.org/bugreport.html⟩

she's not mad, she just wants the config dump. help her help you 🫶

---

🌈 SEE ALSO 🌈

• doveadm(1)

---

that's the whole page bestie, you ate it 💖 stay hydrated, back up your mdbox, and remember: alt storage is not a personality, it's a path ✨

f979264 — April 2026 — Dovecot 🎀 (yeah that's the version stamp and the date, screenshot it, put it in the group chat, whatever, mwah 😘)