Sunday, March 21, 2010

Get offlineimap working with non ASCII characters.


I recently started using offlineimap [1] to manage my GMail accounts locally on my machine.

With offlineimap all my email is local so the navigation is very fast and also I am a little more relieved that I have a local copy of all my email.

The only problem is that offlineimap does not work well with non english characters. This makes it difficult to use for those with labels in Russian, Chinese, Japanese etc [2].

Fortunately offlineimap offers some nice options that allows us to modify it's behavior. Using the "pythonfile" and "nametrans" options I was able to get Japanese working flawlessly.

Problem Description

IMAP4 uses a modified UTF-7 coding for all folder names but offlineimap does not convert the folder names to UTF-8 or something readable before creating local repositories that results in very cryptic folder names like "&MMYwuTDI-".

Some research (googling) on the topic resulted in a very nice code to add IMAP4 UTF-7 encoding capabilities to Python [3]. So with a little time and some copy/paste skills I added this code to offlineimap and ban! I got Japanese working correctly in my folders.

Fixing unicode issues in offlineimap

First we must add the code to convert from IMAP4 UTF7 encoding support to offlineimap. Thanks to Dominic LoBue (offlineimap developer) I learned that we can add our own python code to offlineimap. To do this we created a simple python script (e.g. ~/ that contains the following code (copy/paste from [3]:

Then in our offlineimap configuration file, in the "[general]" section we add a line to load this python script like:

Finally in our remote repository configuration add a nametrans option to convert all foldernames from "imap4-utf-7" encoding to your encoding of preference. My Ubuntu installation is all UTF-8 so I convert all folder names to this encoding:

The "imap4-utf-7" encoding is added by our "" script. With this configuration I can now see the correct Japanese names for all the folders (labels) in my GMail accounts inside Mutt [4].


[3] IMAP4 UTF-7 Encoding/Decoding
[4] Best email client


  1. Anonymous1:21 AM

    This is probably what i'm looking for since my umlauts (åäö) aren't working with gmail & offlineimap, however, two questions:
    1. could you post the code in indented format somewhere, since the version posted (un-indented) won't work.
    2. Is this something that could be included in the upstream source of offlineimap? Have you contacted the developer?
    3. thanks for great work! Very useful, if I get it working. (hehe).

  2. Thanks, I changed the style of the blog some time ago and forgot to apply it to old posts. The code now is indented as it should. Also you can download it from link [3] above. This is just a copy and paste of that code.

    To answer your other question if you read the post you will see that I did contact one developer. He showed me how to do this configuration. No idea if there are any plans to add this to offlineimap but I think they really should.

  3. Just started using offlineimap and bumped into this problem. Thanks a lot. It works like magic for me.

  4. It seems that a recent upgrade causes an error with nametrans. The fix is to add the reverse nametrans function in the local repository as well:

    nametrans = lambda foldername: foldername.decode('utf-8').encode('imap4-utf-7')


    Thank you very much for this module!

  5. Anonymous11:33 PM

    The reverse nametrans solution described by Alexandre doesn't work with version 6.5.5.
    Is there an updated solution?

  6. Anonymous2:53 AM

    Thank you for posting this. I am in a situation very similar to yours and appreciate having an immediate solution.

    I did not realize that IMAP UTF-7 differed so much from regular UTF-7 (as another source I came across claimed the differences were nothing more than swapping the leading plus to an ampersand and adding a hyphen). I had almost settled on a quick-fix python call to iconv, when I came across your superior solution.

    Take care.

  7. Here is a worked version for me:

    OfflineIMAP 6.5.4