Configure file directory boxes

Under certain circumstances, it is preferable to further configure a file directory box. This is done by appending query parameters after the base box URI dir://DIR.

The following parameters are supported:

ParameterDescriptionDefault value
type(Sub-) Type of the directory service(value of “default-dir-box-type”)
workerNumber of worker that can access the directory in parallel7
readonlyAllow only operations that do not create or change zetteln/a


On some operating systems, Zettelstore tries to detect changes to zettel files outside of Zettelstore's control1. On other operating systems, this may be not possible, due to technical limitations. Automatic detection of external changes is also not possible, if zettel files are put on an external service, such as a file server accessed via SMB/CIFS or NFS.

To cope with this uncertainty, Zettelstore provides various internal implementations of a directory box. The default values should match the needs of different users, as explained in the installation part of this manual. The following values are supported:


Is not able to detect external changes. Works on all platforms. Is a little slower than other implementations (up to three times).


Automatically detect external changes. Tries to optimize performance, at a little cost of main memory (RAM).


Internally, Zettelstore parallels concurrent requests for a zettel or its metadata. The number of parallel activities is configured by the worker parameter.

A computer contains a limited number of internal processing units (CPU). Its number ranges from 1 to (currently) 128, e.g. in bigger server environments. Zettelstore typically runs on a system with 1 to 8 CPUs. Access to zettel file is ultimately managed by the underlying operating system. Depending on the hardware and on the type of the directory box, only a limited number of parallel accesses are desirable.

On smaller hardware2, such as the Raspberry Zero, a smaller value might be appropriate. Every worker needs some amount of main memory (RAM) and some amount of processing power. On bigger hardware, with some fast file services, a bigger value could result in higher performance, if needed.

For various reasons, the value should be a prime number. The software might enforce this restriction by selecting the next prime number of a specified non-prime value. The default value is 7, the minimum value is 1, the maximum value is 1499.


Sometimes you may want to provide zettel from a file directory box, but you want to disallow any changes. If you provide the query parameter readonly (with or without a corresponding value), the box will disallow any changes.

box-uri-1: dir:///home/zettel?readonly

If you put the whole Zettelstore in read-only mode, all configured file directory boxes will be in read-only mode too, even if not explicitly configured.

  1. This includes Linux, Windows, and macOS. ↩︎
  2. In comparison to a normal desktop or laptop computer ↩︎