Version 20.1 by slauriere on 2018/09/17

Below you have the configuration for UTF-8. Note that this is valid for XWiki 1.0 b5 and above. Easier configuration might be provided for upcoming releases.

XWiki encoding

Change the charset encoding in these XWiki files:

  • web.xml: locate the filter class org.xwiki.container.servlet.filters.internal.SetCharacterEncodingFilter and change it to UTF-8. It should look like this:
       <filter-name>Set Character Encoding</filter-name>
  • xwiki.cfg : locate the line containing xwiki.encoding and change it to look like this:
    xwiki.encoding = UTF-8

HTML encoding

Change the HTML encoding in XWiki through Administration --> Look & Feel --> Page Elements --> HTTP Meta Info. 

The HTTP Meta Info section was located in Administration --> Presentation in older versions of XWiki.

Inside this textbox locate the Content-type meta tag and make it look like this, changing the encoding to UTF-8

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

This step is not needed if you have the following. Instead that line can be left alone.

<meta http-equiv="Content-Type" content="text/html; charset=$!xwiki.encoding" />

Database configuration


It's common practice that the MySQL configuration file, in *nix systems is located in $$/etc/mysql/my.cnf:
Starting with MySQL 5.5.3 the option 'default-character-set=utf8' is deprecated under [mysql]

character-set-server = utf8
collation-server = utf8_bin

After 5.5.3

character-set-server = utf8
collation-server = utf8_bin

Servlet Container


echo off
rem set LANG=fr_FR.ISO8859-1
set LANG=en_US.UTF-8
set JETTY_PORT=8080
java %JAVA_OPTS% -Djetty.port=%JETTY_PORT% -Djetty.home=%JETTY_HOME% -Dfile.encoding=UTF-8 -jar %JETTY_HOME%/start.jar

Instead of the config system variable LANG you can use JVM properties.


in server startup script.


In order to enable UTF-8 in tomcat, you have to add


to each connector enabled/used in conf/server.xml. For example the non-SSL HTTP Connector should read:

<Connector port="8080" maxHttpHeaderSize="8192"
   maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
   enableLookups="false" redirectPort="8443" acceptCount="100"
   connectionTimeout="20000" disableUploadTimeout="true"

In case you're using AJP to connect Tomcat and httpd, make sure you add this attribute to the AJP connector.


To run XWiki with UTF-8 in Glassfish you will need to recreate the XWiki WAR file and do a change to the glassfish config. First, in the Administration GUI under Domain => General => Locale enter en_US.UTF-8.

Now you will need to add all the aforementioned changes from this document to the files in the war file, create a new warfile, and deploy that one to your glassfish installation. This is required due to the fact that Glassfish will not accept changes to a deployed web.xml file. So you need to deploy a ready changed web.xml file inside your war file because all subsequent changes to the deployed web.xml file in the filesystem are totally ignored.

Create a new directory that we will use as a temporary place to edit our war file:

mkdir xwikitmp

Unpack the warfile (replace <suffix> with the proper name for the version of XWiki you're using):

cd xwikitemp;jar xvf ../xwiki-<suffix>.war

Edit the files as mentioned in the beginning of this article:

  • wiki.cfg
  • web.xml
  • hibernate.cfg.xml

Now let's create a new warfile which contains all the changes:

jar cvf ../xwiki-<suffix>.war .

Now you can deploy your new .war file to Glassfish and it will have all the changes in it and wll be correctly deployed.

Web server


Make sure that the Apache configuration file httpd.conf contains the following line:

AddDefaultCharset UTF-8

System config

Add the following variables to your system:

LANG = en_US.UTF-8


OpenOffice import

If OpenOffice import turns characters into question marks or HTML Entity you need to edit registrymodifications.xcu located in user profile used by the OO server by adding:

oor:name="Encoding" oor:op="fuse"><value>76</value></prop></item>



  • The Admin Tools extension can be helpful to identify the values of the XWiki encoding configuration parameters on a running server.

Get Connected