Last modified by Ecaterina Moraru (Valica) on 2020/01/28

A multi-tenant setup (a.k.a "virtual mode", "multi-wiki" or "farm mode") allows you to have several wikis running on the same XWiki instance (i.e. in the same JVM).

This is implemented by having each wiki have its own schema or its own database in the DBMS (whether it's implemented as schema or databases depends on the DBMS).

The main advantage of multi-tenancy is performance optimization. A single XWiki instance on a physical machine (thus a single Servlet Container) will perform much better than having several XWiki instances running on the same machine, which wouldn't scale. As an example known XWiki multi-tenant instances host several hundreds to several thousands wikis on a single XWiki instance.


The multi-tenancy feature is currently supported only on some DBMS:

  • MySQL (using a different database for each subwiki)
  • Oracle (using a different schema for each subwiki)
  • HSQLDB (using a different schema for each subwiki) Starting with XWiki 4.3
  • PostgreSQL (using a different schema for each subwiki) Starting with XWiki 5.0 Also note that using different databases instead of schemas is not currently supported on PostgreSQL since the JDBC driver doesn't support setCatalog() for changing databases. That's because PostgreSQL connections are pointed to a specific database at connection time (see jira issue XWIKI-1960 for details).
  • Derby is currently not supported

In addition to having a supported DBMS you'll also need:

  • To choose one instance of XWiki that has been installed on your network and that wil act as the main wiki. The database name for this wiki should be xwiki. If you've still got to install the XWiki instance, please refer to the installation guide and install XWiki first.
  • Admin privileges on this XWiki instance
  • You need to be sure that the xwiki user used to create the main database has the correct permissions to be able to create other schemas or databases since each subwiki will create a new schema/database. Refer to the Databases install guides.


There's no special step to take to get the multi-tenant feature since it's a builtin feature. We're providing a UI for users to make it easier to create, configure and delete sub wikis via the Wiki Application which should be installed by default. If you upgrade from an older version you can install it via the Extension Manager.

Hostname based subwikis

By default subwikis are reachable via URLs having the wiki name in its path section, like If you want to have your subwikis recognized by the hostname, like you need to change the configuration on the file system:

  • Set url.standard.multiwiki.isPathBased=false in the WEB-INF/ file and set xwiki.virtual.usepath=0 in the WEB-INF/xwiki.cfg file.
  • Restart your XWiki instance

If you already have created subwikis with the path-based layout you might want to go through all wikis via the Wiki Index and make sure they have one alias for every hostname under which the subwiki should be reachable. 

Configuration prior to XWiki 5.3

Before 5.3, we're providing a different UI to manage sub wikis. For this you need to install the Wiki Manager Application (see that page for installation instructions). This application will be transparently replaced with the Wiki Application when upgrading to 5.3 or later. 

Configuration prior to XWiki 5.0

These steps are no longer needed if you use XWiki 5.0 or newer.

  • Stop your XWiki instance, edit the WEB-INF/xwiki.cfg file, look for the xwiki.virtual property and set it to 1: xwiki.virtual=1
  • Restart your XWiki instance

Get Connected