This document explains how to organize, edit and manage your local configuration options. For a list of the actual options, see Site settings reference for maintainers
require a database migration
have commercial consequences like a changed hosting price or a fee for modifying them.
This file contains configuration options which the site operator might want to discuss with their site maintainer. That’s why every Lino application should provide in its documentation a list of available configuration options.
- site setting¶
For example the
class Site(Site): languages = "en fr"
- site feature¶
For example the
- plugin setting¶
For example the
def get_plugin_configs(self): yield super(Site, self).get_plugin_configs() ... yield ('notify', 'remove_after', 24*7)
To edit your local
settings.py file, go to the project directory and
start your preferred editor on it:
go mysite nano settings.py
A minimal Lino
settings.py contains something like this:
from foo.bar.settings import * SITE = Site(globals()) # more local settings here
That is, you import the default settings of some Lino application into
your local settings module, including a
Site class, then you
Site class and store this instance in a variable
SITE. Every Lino site requires a setting named
settings.py file must be valid Python syntax. One pitfall if you
have no experience with Python is that indentation is important. Also make
sure that your text editor doesn’t replace spaces by tabs.
In case of doubt, before restarting the server, you may issue the
following command to test whether your
settings.py is okay:
$ python manage.py validate
You might be surprised to see the following construct:
from foo.bar.settings import * class Site(Site): title = "My title" SITE = Site(globals())
We are just using a feature of the Python language that allows us to define a new class based on an existing class and having the same name as its parent.
settings.py file generated by getlino also adds the following:
def get_plugin_configs(self): yield super(Site, self).get_plugin_configs() # example of local plugin settings: # yield ('ledger', 'start_year', 2018)
That is, you override the
The first argument of the instantiator must be the global namespace of your settings module (globals()). Lino uses this to fill “intelligent default values” to your settings module’s global namespace.
Note that Lino writes to your settings module’s global namespace only
while the Site class gets instantiated. So if for some reason you
want to modify one of the settings, do it after your
You’ve maybe heard that it is not allowed to modify Django’s settings
once it has started. But there’s nothing illegal with this here
because this happens before Django has seen your
Lino does more than this. It will for example read the __file__
attribute of this, to know where your
settings.py is in the
Here are some of the Django setting for which Lino sets default values:
DATABASES: a SQLite database in a file
default.dbin your project directory. On a production server you are of course going to set your own
DATABASES, but this default value is the best choice for beginners.
ROOT_URLsetting and the files
polls/views.pygenerated by Django are not necessary. With Lino you don’t need to worry about URLs and views because Lino defines them for you.
settings.py files are small¶
settings.py file for a Lino site consists of a few lines
(plus, on a production site, the lines for defining your
setting). Compare this to a
settings.py file generated by Django’s
startproject command which contains 120 lines of text (Django version
>>> from atelier.sheller import Sheller >>> shell = Sheller() # will run in a temporary directory >>> shell("django-admin startproject foo") >>> shell("wc -l foo/foo/settings.py") 120 foo/foo/settings.py >>> shell("django-admin --version") 3.1.7
The Django settings module is the most important thing in Django. Almost everything you do with Django requires the settings module to be loaded. Django does that automagically as soon as a Python process accesses the settings. And when that moment arrives, Django needs to know the name of your settings module.
To illustrate what happens when Django doesn’t know the settings module, let’s
open a Python session in an environment with Django installed but without any
DJANGO_SETTINGS_MODULE environment variable defined, and then type:
>>> from django.conf import settings
This will pass. We said almost everything requires the settings to be loaded.
You may import the
django.conf.settings module. But as soon as you want
to actually access some attribute of this module, you will get an
>>> print(settings.DEBUG) Traceback (most recent call last): ... django.core.exceptions.ImproperlyConfigured: Requested setting DEBUG, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.
A Django settings module must be importable. That is, if
DJANGO_SETTINGS_MODULE contains e.g.
Django will do the equivalent of
We use to speak about “the
settings.py file”, but in reality the
Django settings module can be in some arbitrary filename. Some Django
sites use a layout called a settings package, which is
useful when you want to have different variants of settings modules.
In some projects we use a whole package of settings:
settings/__init.py: the base for all modules of this package.
settings/demo.py: instantiates a
SITEvariable and thus is designed to be used directly as a
A Lino server configured using getlino can provide a module with
server-wide default settings for this server, and individual sites can decide to
import these. Such a module (despite the fact that it is also in a file named
settings.py) is not a Django settings module.
Every site user may choose one of these languages in their user preferences.
Lino uses the same language codes as Django.
- language code¶
A code that identifies a language for which screen messages have been translated.
You can see the list of available languages in django/conf/global_settings.py.
You may use any of these languages, but Lino-specific messages are currently being translated only into German, French, Estonian and Dutch. You are welcome to contribute translations to your language of choice. See https://www.lino-framework.org/dev/translate
Having more than one language in your language distribution will make your Lino site multilingual. Changing this setting may change your database structure and thus might require a data migration. This is because this setting also controls how multilingual database content is stored in your database.
- Django settings module¶
A module that is imported by a Python process when it uses Django. It is just a Python module with module-level variables, most of them upper-case. It is usually stored in a file named
The environment variable that is expected to contain the Python name of the Django settings module.