Backing up your Gmail account with Gmvault

Gmail Web-based applications probably have as many pros as they do cons. But two of the biggest cons are that 1) your data is on someone else’s server, and 2) it can be difficult (if not impossible) to back up that data when you need to. Or ever.

That’s especially true for web-based email. Sure, you can install a desktop email client like Mozilla Thunderbird and hook that into your web mail account. You get a backup, and a way to use your account from your desktop.

If you think that solution is a bit to cumbersome and you use Gmail, then you might want to give Gmvault a peek. A command line tool, it provides a quick and easy way of backing up messages and folders in Gmail.

Let’s take a closer look at Gmvault.

Downloading and installing

Gmvault is a cross-platform tool – it’s available for Windows, Mac OS, and Linux. Let’s confine ourselves to Linux, why don’t we? You can download either a binary installer or the Python source files.

I installed it using the Python source package. To do the installation, I extracted the files from the archive that I downloaded. Then, I cracked open a terminal window, navigated to the directory containing the installation files, and then typed:

sudo python install

After entering my password, the Gmvault script and its supporting files were installed. From there, I was ready to go.

Backing up your Gmail account

To do that, open a terminal window and run the following command:

gmvault sync

Where YourAccount is your Gmail account name.

You’ll be asked to authorize your account. That just tells Gmail to give the Gmvault script access to your account.


From there, the script downloads everything in your Gmail account – all messages, and all folders. This can take a while, depending on how many messages you have saved. If you’re like most Gmail users, that’s a lot.

Downloading messages

The files are stored in a folder in your home directory called gmvault_db. Don’t worry. It’s not an actual database. It’s just a directory with a bunch of subfolders, each containing information about the emails that you’ve downloaded. The folders are named after the months and years in which you received the messages – for example 2009–06 contains all the messages you received in June, 2009.

Gmvault folder on your computer

Individual emails are stored in a compressed file, with the .eml extension. That’s a widely-used format for storing email messages. If you want to view an email, you need to uncompress the file and then open the .eml file in a text editor.

An example message

The biggest problem you’ll run into is knowing which message is which. The compressed files don’t have very intuitive file names – they have names like 1247757563864116657.eml.gz.

But I don’t want to backup all of my messages!

Gmvault can selectively download messages using, among other things, the following criteria:

  • A specific folder
  • The email address of a sender

Let’s say you want to back up only the messages in a folder named Books. To do that, run the following command:

gmvault sync –type custom –gmail-req ‘in:Books’ ‘’

On the other hand, you might only want to back up emails from your sister Karen. To do that, run the following command:

gmvault sync –type custom –gmail-req ‘from:Karen’ ‘’

The script will look for messages with Karen in the From field and grab those.

Restoring your messages

Let’s assume that something happened to your Gmail account. Maybe it got wiped out in a solar flare. Maybe it got cracked and said cracker deleted all of your messages. Using Gmvault, you can restore what you’ve backed up. How? By running the following command:

restore -d ~/gmvault-db

That restores everything. If you only want to restore the last two months’ worth of email, use this command instead:

restore –type quick -d ~/gmvault-db

Final thoughts

Gmvault is a quick and effective way of backing up and restoring the messages in your Gmail account. And if you decide you don’t want to use Gmail anymore, it’s a great way to archive your messages before closing your account.

This work is licensed under a Creative Commons Attribution 4.0 International License.

flattr this!

  • EmilBB

    Nice, thank you.  One question tho: When you back up again, does it understand that it should only backup the new emails that haven’t been downloaded before?

  • Scott Nesbitt

    Glad you enjoyed the post. As for your question, I’m about 99% sure that after its first run Gmvault only grabs the most recent emails in your inbox and various folders. To be honest, I don’t watch the terminal window too closely when Gmvault runs. But I vaguely recall it doing what appeared to be skipping messages that were already backed up, and subsequent runs of the application seemed to go a bit faster.

    Of course, that could be my imagination. And I’ll gladly take my lumps if I’m wrong!

  • bnj


    in order to download only new email from gmail, you have to execute the following command:
    gmvault sync –t quick ‘’

  • daaus

    I did the above, all okay, but when I did the sync command.. I get

    error: Invalid credentials XXXXXXXXXXXXXXXXXXXX

    === End of Exception traceback ===
    How do I overcome this error? I checked in google account & gmvault has granted access

  • Scott Nesbitt

    I’d suggest contacting the developers about this. You can do that here:

  • daaus

    RE: error: Invalid credentials
    – the developer helped quickly and I got there. I had put in the
    incorrect email address, to our gmail domain, instead of a specific
    domain user email. So I deleted the home directory authorisation file
    under .gmvault (hidden file under HOME), and then put in the sync
    command again with the instead of which was
    put in previously. Hope this helps people who make the same error.