Installation instructions


Python (2.7)
Django (>= 1.4)
Translate-toolkit (>= 1.9.0, 1.10.0 or newer strongly recommended)
GitPython (>= 0.3.2)
Git (>= 1.7.2)
python-social-auth (>= 0.1)
Whoosh (>= 2.5, 2.5.2 is recommended)
PIL or Pillow library
libravatar (optional for federated avatar support)
PyICU (optional for proper sorting of strings)
Database backend
Any database supported in Django will work, check their documentation for more details.

Requirements on Debian or Ubuntu

On Debian or Ubuntu, most of requirements are already packaged, to install them you can use apt-get:

apt-get install python-django translate-toolkit python-git \
    python-whoosh python-pil python-django-south python-libravatar python-pyicu

# Optional for database backend

apt-get install python-mysqldb   # For MySQL
apt-get install python-psycopg2  # For PostgreSQL

There is one library not available in Debian so far, so it is recommended to install it using pip:

pip install python-social-auth

Requirements on openSUSE

All requirements are available either directly in openSUSE or in devel:languages:python repository:

zypper install python-django python-social-auth translate-toolkit python-GitPython \
    python-whoosh python-imaging python-South

Requirements on OSX

If your python was not installed using brew, make sure you have this in your .bash_profile file or executed somehow:

export PYTHONPATH="/usr/local/lib/python2.7/site-packages:$PYTHONPATH"

This configuration make available the installed libraries to python

Requirements using pip installer

Most requirements can be also installed using pip installer:

pip install -r requirements.txt

Also you will need header files for libxml2 and libxslt to compile some of the required Python modules.

On Debian or Ubuntu you can install them using:

apt-get install libxml2-dev libxslt-dev

On openSUSE or SLES you can install them using:

zypper install libxslt-devel libxml2-devel

Filesystem permissions

Weblate process needs to be able to read and write to two directories where it keeps data. The GIT_ROOT is used for storing Git repositories and WHOOSH_INDEX is used for fulltext search data.

The default configuration places them in same tree as Weblate sources, however you might prefer to move these to better location such as /var/lib/weblate.

Weblate tries to create these directories automatically, but it will fail when it does not have permissions to do so.

You should also take care when running Management commands, as they should be run under same user as Weblate itself is running, otherwise permissions on some files might be wrong.


Copy weblate/ to weblate/ and adjust it to match your setup. You will probably want to adjust following options:


List of site administrators to receive notifications when something goes wrong, for example notifications on failed merge or Django errors.


If you are running Django 1.5 or newer, you need to set this to list of hosts your site is supposed to serve. For example:



Connectivity to database server, please check Django’s documentation for more details.


When using MySQL, don’t forget to create database with UTF-8 encoding:



Disable this for production server. With debug mode enabled, Django will show backtraces in case of error to users, when you disable it, errors will go by email to ADMINS (see above).

Debug mode also slows down Weblate as Django stores much more information internally in this case.


Email sender address for outgoing email, for example registration emails.


Key used by Django to sign some information in cookies, see Django secret key for more information.


Email used as sender address for sending emails to administrator, for example notifications on failed merge.

After your configuration is ready, you can run ./ syncdb and ./ migrate to create database structure. Now you should be able to create translation projects using admin interface.

In case you want to run installation non interactively, you can use ./ syncdb --noinput and then create admin user using createadmin command.

You should also login to admin interface (on /admin/ URL) and adjust default site name to match your domain.


If you are running version from Git, you should also regenerate locale files every time you are upgrading. You can do this by invoking script ./scripts/generate-locales.

Production setup

For production setup you should do following adjustments:

Disable debug mode

Disable Django’s debug mode by:

DEBUG = False

With debug mode Django stores all executed queries and shows users backtraces of errors what is not desired in production setup.

See also


Properly configure admins

Set correct admin addresses to ADMINS setting for defining who will receive mail in case something goes wrong on the server, for example:

    ('Your Name', ''),

See also


Set correct site name

Adjust site name in admin interface, otherwise links in RSS or registration emails will not work.

Enable indexing offloading

Enable OFFLOAD_INDEXING to prevent locking issues and improve performance. Don’t forget to schedule indexing in background job to keep the index up to date.

Use powerful database engine

Use powerful database engine (SQLite is usually not good enough for production environment), for example setup for MySQL:

    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'weblate',
        'USER': 'weblate',
        'PASSWORD': 'weblate',
        'HOST': '',
        'PORT': '',

Enable caching

If possible, use memcache from Django by adjusting CACHES configuration variable, for example:

    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': '',

Configure email addresses

Weblate needs to send out emails on several occasions and these emails should have correct sender address, please configure SERVER_EMAIL and DEFAULT_FROM_EMAIL to match your environment, for example:


Allowed hosts setup

Django 1.5 and newer require ALLOWED_HOSTS to hold list of domain names your site is allowed to serve, having it empty will block any request.

Federated avatar support

By default, Weblate relies on <> for avatars. When you install pyLibavatar, you will get proper support for federated avatars.

PyICU library

PyICU library is optionally used by Weblate to sort Unicode strings. This way language names are properly sorted even in non-ASCII languages like Japanese, Chinese or Arabic or for languages with accented letters.

Django secret key

The SECRET_KEY setting is used by Django to sign cookies and you should really use own value rather than using the one coming from example setup.

You can generate new key using examples/generate-secret-key shipped with Weblate.

Admin static files

If you see purely designed admin interface, the CSS files required for it are not loaded. This is usually if you are running in non-debug mode and have not configured your web server to serve them. Recommended setup is described in the Running server chapter.

See also

Running server

Home directory

The home directory for user which is running Weblate should be existing and writable by this user. This is especially needed if you want to use SSH to access private repositories.


On Linux and other UNIX like systems, the path to user’s home directory is defined in /etc/passwd. Many distributions default to non writable directory for users used for serving web content (such as apache, www-data or wwwrun, so you either have to run Weblate under different user or change this setting.

Running server

Running Weblate is not different from running any other Django based application.

It is recommended to serve static files directly by your web server, you should use that for following paths:

Serves media directory from Weblate.
Serves media files for Django admin interface (eg. /usr/share/pyshared/django/contrib/admin/media/).

Additionally you should setup rewrite rule to serve media/favicon.ico as favicon.ico.

Sample configuration for Lighttpd

The configuration for Lighttpd web server might look like following (available as examples/lighttpd.conf):

fastcgi.server = (
    "/weblate.fcgi" => (
        "main" => (
            "socket" => "/var/run/django/weblate.socket",
            "check-local" => "disable",
alias.url = (
    "/media" => "/var/lib/django/weblate/weblate/media/",
    "/static/admin" => "/usr/share/pyshared/django/contrib/admin/static/admin/",

url.rewrite-once = (
    "^(/*media.*)$" => "$1",
    "^(/*static.*)$" => "$1",
    "^/*favicon\.ico$" => "/media/favicon.ico",
    "^/*robots\.txt$" => "/media/robots.txt",
    "^(/.*)$" => "/weblate.fcgi$1",

expire.url                  = (
    "/media/" => "access 1 months",
    "/static/" => "access 1 months",
    "/favicon.ico" => "access 1 months",

Sample configuration for Apache

Following configuration runs Weblate as WSGI, you need to have enabled mod_wsgi (available as examples/apache.conf):

# VirtualHost for weblate
WSGIPythonPath /usr/share/weblate
<VirtualHost *:80>

    DocumentRoot /usr/share/weblate/weblate/media/

    Alias /robots.txt /usr/share/weblate/weblate/media/robots.txt
    Alias /favicon.ico /usr/share/weblate/weblate/media/favicon.ico

    Alias /media/ /usr/share/weblate/weblate/media/
    Alias /doc/ /usr/share/doc/packages/weblate/html/
    Alias /static/admin /usr/lib/python2.7/site-packages/django/contrib/admin/static/admin/

    <Directory /usr/lib/python2.7/site-packages/django/contrib/admin/static/admin/>
        Order deny,allow
        Allow from all

    <Directory /usr/share/weblate/weblate/media/>
        Order deny,allow
        Allow from all

    <Directory /usr/share/doc/packages/weblate/html/>
        Order deny,allow
        Allow from all

    <Directory /usr/share/weblate/weblate/examples/>
        Order deny,allow
        Allow from all

    WSGIScriptAlias / /usr/share/weblate/weblate/
    WSGIPassAuthorization On

    <Directory /usr/share/weblate/weblate>
        Order deny,allow
        Allow from all


Sample configuration for nginx

Following configuration runs Weblate as uwsgi under nginx webserver.

Configuration for nginx (also available as examples/weblate.nginx.conf):

server {
	listen 80;
	server_name weblate;
	root /path/to/weblate/weblate;

	location /favicon.ico {
		root /path/to/weblate/weblate/media;
		expires 30d;

	location /media/ {
		root /path/to/weblate/weblate;
		expires 30d;

	location /robots.txt {
		root /path/to/weblate/weblate/media;
		expires 30d;

	location /static/admin/ {
		root /usr/local/lib/python2.7/dist-packages/django/contrib/admin;
		expires 30d;

	location / {
		include uwsgi_params;

Configuration for uwsgi (also available as examples/weblate.uwsgi.ini):

plugins       = python
master        = true
protocol      = uwsgi
socket        =
wsgi-file     = /path/to/weblate/weblate/
python-path   = /path/to/weblate

Running Weblate under path

Minimalistic configuration to serve Weblate under /weblate (you will need to include portions of above full configuration to allow access to the files). Again using mod_wsgi (also available as examples/apache-path.conf):

# Example Apache configuration for running Weblate under /weblate path

# Path to Weblate code
WSGIPythonPath /usr/share/weblate

# Path to Weblate WSGI handler
WSGIScriptAlias /weblate "/usr/share/weblate/weblate/"

# Aliases to serve media and static files
Alias /weblate/media/ /usr/share/weblate/weblate/media/
Alias /static/admin /usr/lib/python2.7/site-packages/django/contrib/admin/static/admin/

Additionally you will have to adjust weblate/

URL_PREFIX = '/weblate'


This is supported since Weblate 1.3.


Weblate appliance provides preconfigured Weblate running with MySQL database as backend and Apache as web server. It is provided in many formats suitable for any form of virtualization, cloud or hardware installation.

It comes with standard set of passwords you will want to change:

Username Password Scope Description
root linux System Administrator account, use for local or SSH login
root   MySQL MySQL administrator
weblate weblate MySQL Account in MySQL database for storing Weblate data
admin admin Weblate Weblate/Django admin user

The appliance is built using SUSE Studio and is based on openSUSE 12.3.

You should also adjust some settings to match your environment, namely:

Migrating Weblate to another server

Migrating Weblate to another server should be pretty easy, however it stores data in few locations which you should migrate carefully. The best approach is to stop migrated Weblate for the migration.

Migrating database

Depending on your database backend, you might have several options to migrate the database. The most straightforward one is to dump the database on one server and import it on the new one. Alternatively you can use replication in case your database supports it.

Migrating Git repositories

The Git repositories stored under GIT_ROOT need to be migrated as well. You can simply copy them or use rsync to do the migration more effectively.

Migrating fulltext index

For the fulltext index (stored in WHOOSH_INDEX) it is better not to migrate it, but rather to generate fresh one using rebuild_index.

Other notes

Don’t forget to move other services which Weblate might have been using like memcached, cron jobs or custom authentication backends.

Read the Docs v: weblate-1.8
On Read the Docs
Project Home

Free document hosting provided by Read the Docs.