Pelican 3.3 pelican-quickstart error “ValueError: unknown locale: UTF-8”

Each Answer to this Q is separated by one/two green lines.

When I was trying to use pelican3.3, I typed the commend “pelican-quickstart”, some errors showed up.

These are the errors:

(PelicanEnv)59-127-113-90:myblog Richo$ pelican-quickstart
Traceback (most recent call last):
  File "/Users/Richo/Dropbox/Github/PelicanEnv/bin/pelican-quickstart", line 9, in <module>
    load_entry_point('pelican==3.3', 'console_scripts', 'pelican-quickstart')()
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/", line 378, in load_entry_point
    return get_distribution(dist).load_entry_point(group, name)
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/", line 2566, in load_entry_point
    return ep.load()
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/", line 2260, in load
    entry = __import__(self.module_name, globals(),globals(), ['__name__'])
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/pelican/", line 16, in <module>
    from pelican.generators import (ArticlesGenerator, PagesGenerator,
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/pelican/", line 20, in <module>
    from pelican.readers import Readers
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/pelican/", line 11, in <module>
    import docutils.core
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/docutils/", line 20, in <module>
    from docutils import frontend, io, utils, readers, writers
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/docutils/", line 41, in <module>
    import docutils.utils
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/docutils/utils/", line 20, in <module>
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/docutils/", line 18, in <module>
    from docutils.utils.error_reporting import locale_encoding, ErrorString, ErrorOutput
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/site-packages/docutils/utils/", line 47, in <module>
    locale_encoding = locale.getlocale()[1] or locale.getdefaultlocale()[1]
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/", line 513, in getdefaultlocale
    return _parse_localename(localename)
  File "/Users/Richo/Dropbox/Github/PelicanEnv/lib/python2.7/", line 445, in _parse_localename
    raise ValueError, 'unknown locale: %s' % localename
ValueError: unknown locale: UTF-8

My OS is OS X Mavericks.

You could try a solution posted here or here. Basically, add some lines to your ~/.bash_profile:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

There is an outstanding bug report related to this issue. It appears that Python makes some assumptions about the format of locale names that aren’t universally valid. Explicitly setting these environment vars is basically just a workaround for that bug.

[Edit:] As @asmeurer correctly points out, the above fix assumes English and the U.S. You should really pick your preferred locale from the list given by locale -a (generally one that ends in UTF-8).

Gerrat’s answer works, and I believe we should mention that if you use somthing like zsh, you should add lines to ~/.zshrc instead of ~/.bash_profile or ~/.bash_rc

Upstairs answers were quick great! But I believe people lazy like me want to change the global environment in case never change again while change to another Login user. So we need to change the file like:

sudo vi /etc/profile or sudo vi /etc/bashrc

And then add the two line in the following files

export LC_ALL="en_US.UTF-8"
export LANG="en_US.UTF-8"

Remember do not miss one of them, it doesn’t work for me just $LANG or $LC_ALL. After that run the command to active the environment.

sudo source /etc/profile 
sudo source /etc/bashrc
source ~/.bash_profile 
source ~/.zshrc

Again, lazy people like me can finish in one line command.

echo -e "export LC_ALL=en_US.UTF-8\nexport LANG=en_US.UTF-8" >> ~/.bash_profile && source ~/.bash_profile

I’m reposting my answer from this question here, since that it was marked as a duplicate of this one, and the accepted answer on this question is wrong in many ways.

This is a bug in the OS X Terminal app that only shows up in certain locales (country/language combinations). Open Terminal in /Applications/Utilities and uncheck the box “Set locale environment variables on startup”.

enter image description here

This will set your LANG environment variable to be empty. This may cause terminal use to incorrect settings for your locale. The locale command in the Terminal will tell you what settings are used. To use the correct language, add a line to your bash profile (typically ~/.profile)

export LANG=your-lang

Replace your-lang with the correct locale specifier for your language. The command locale -a will show you all the specifiers. For example, the language code for US English is en_US.UTF-8. The locale affects what translations are used when they are available, and also how dates, currencies, and decimals are formatted.

Note, this image and content were taken from (I’m also the original author of that page).

None of the solutions mentioned here worked for me running a python 3.7 project in a local app engine environment.

Although I could retrieve the locale through the command line just fine:

python3 -c 'import locale; print(locale.getdefaultlocale());'
('en_US', 'UTF-8')  

That locale could not be found within the app engine environment:

File "/usr/local/Cellar/python/3.7.3/Frameworks/Python.framework/Versions/3.7/lib/python3.7/", line 568, in getdefaultlocale
    return _parse_localename(localename)
File "/usr/local/Cellar/python/3.7.3/Frameworks/Python.framework/Versions/3.7/lib/python3.7/", line 495, in _parse_localename
    raise ValueError('unknown locale: %s' % localename)
ValueError: unknown locale: UTF-8

So I had to explicitly set env_variables in my app.yaml file:

  LC_ALL: "en_US:UTF_8"
  LC_CTYPE: "en_US:UTF_8"

And that solved the bug.

For some reason I also needed:

export LC_CTYPE=en_US.UTF-8

The answers/resolutions are collected from stackoverflow, are licensed under cc by-sa 2.5 , cc by-sa 3.0 and cc by-sa 4.0 .

Leave a Reply

Your email address will not be published.