Adherence to XDG Base Directory Specification

Personally I think there is a good reason for Joplin to fully support the XDG Base Directory Specification. There was a previous PR raised for this but it was closed (Desktop: Resolves #6085 Add initial support for XDG Folder Specs by BeatLink · Pull Request #6152 · laurent22/joplin · GitHub) as well as a number of other GH "issues" and a forum post that gained no traction so this isn't a new topic by any means, I'm most certainly not the first who has brought this up or thought about it.

It has been on my mind for a while but was kind of spurred on by this video which is a nicely accessible discussion on the XDG spec and why you should or should not adhere to it.

Currently Joplin doesn't adhere to this using the variables (please correct if wrong), it instead directly writes its config and data to $HOME/.config

This is just my rambling thoughts on the topic, I do think it is worthy of a proper discussion and if nothing else allows us to link back to here if people bring the topic up so we can say "yes", "no" or "in progress" and why.


Some of the benefits I believe this would bring include:

  • Better support of some features of the Appimage format (which is the only official distribution on Linux).

    • I go into further detail here but the gist of it is that Appimage supports a "portable mode" by setting variables for where the app should consider its home dir. This currently only partially works with Joplin (the .home dir works as it sets $HOME but .config does not as it uses $XDG_CONFIG_HOME) so currently is only "mostly" portable.
    • This would better complement the concept of the Windows portable version and we could add documentation on how this is accomplished on Linux to make it an official method.
  • Allows users who actually set their XDG base directory variables to something else to actually have it followed rather than being forced to symlink or similar.

  • Better native support of some of the other "unofficial" distributions such as Flatpak (and Snap?). Potentially other packaging formats with similar sandboxing options or portable modes could also benefit from this change.

  • Users of the official distribution should see almost no changes in functionality, most distributions don't explicitly set XDG variables (as far as I understand) so defaults to ~/.config anyway. Only users with those variables set elsewhere or using other Joplin distributions may be affected by the change.

  • If taken further we could "de-clutter" a user's home directory. Currently I have (for the desktop app): ~/.joplin, ~/.config/Joplin and ~/.config/joplin-desktop. (I'm sure there used to be a .config/@joplin, has that gone away or am I imagining things?).

    • ~/.joplin is admittedly due to the recommended install script so not sure if there is a standard for where this should actually be installed for appimages but the spec states that executables should be in ~/.local/bin.
    • ~/.config/Joplin is the Electron cache and really seems like it should be stored in ~/.cache rather than ~/.config which is what the spec suggests ($XDG_CACHE_HOME). Not sure if this is set by Joplin though or by Electron itself?
    • ~/config/joplin-desktop is the actual Joplin profile dir and is definitely (maybe? More on that later) in the correct place however it places it here without checking $XDG_CONFIG_HOME.


I can also see valid criticism or opposition to this change:

  • Is it really that much of a problem? The majority probably don't care about this so is this just sating the needs of a very few select people?

  • Might cause unintended bugs or issues for existing users thinking that their data has suddenly been lost if Joplin suddenly creates a new profile in a different location.

    • The above is particularly valid for any users of "unofficial" distributions - many Linux Mint users have the Flatpak installed as it is listed in the software center.
  • "Migrating" existing users - some simply might be used to how it currently works and rely on it. Would we force a migration? Add it as an option and alert the user? If given an option, how long would we continue to support (if at all) any "old" method if a user choses not to migrate their data where necessary?

  • If we are going to the lengths of following the spec, whilst a config file such as settings.json or userchrome.css clearly belongs as a "user-specific configuration file", the same cannot be said of database.sqlite or the resources directory. Following the spec, should these actually belong in $XDG_DATA_HOME (i.e. ~/local/share) as they are arguably "user-specific data files".

    • This would obviously be a rather major change, would require a lot of documentation refactoring and checking on guides to make sure information is still relevant. Will also make a lot of old forum posts obsolete or at least misleading.
  • Could this break plugins if they also hard code the path to ~/.config rather than getting it from the API?

Other OSs


I'm not sure if there is a formal specification as such but it does seem strange how the XDG spec is sort of followed on Windows rather than its native version. For example it makes sense that really the profile should be stored in %appdata%\joplin-desktop rather than %userprofile%\.config\joplin-desktop.

  • Problems are much the same as above but unlike Linux this would 100% have an effect on existing users of the official (installed) distribution.


I'm not that familiar with macOS, does it also use the XDG spec? If so then the above points still (mostly) apply. If not officially then should we still support the structure of the itself ?

Interested to hear opinions of those more knowledgeable than I on such matters so tell me if I'm spewing rubbish.


In my opinion, the path %APPDATA% is not the right one under Windows, since this is also syncronized in companies with roaming profiles, and this can lead to problems with large profiles and the SQLLite DB.
I think rather %LOCALAPPDATA% is the right path, since this data is not transferred to other servers.


Yeah, and the folder name should probably be just "Joplin", not "joplin-desktop". In other words, %LOCALAPPDATA%\Joplin. This is what most software do — the folder name is the same as the application name presented to the user.

joplin is the name of the terminal app profile directory, it would cause untold carnage to those who use both on a system.

For Snap at least, the sandboxing is exactly why the default behaviour is to overwrite any system XDG variables by default, so if Joplin started to respect the variable, you'll still find that the snap build would only ever read/write to exactly where it currently does anyway, which is away from the hosts preferred folder.

1 Like

Well, it could always be %LOCALAPPDATA%\Joplin\joplin-desktop and %LOCALAPPDATA%\Joplin\joplin (maybe rename to joplin-cli to avoid confusion?) then. At least the parent folder would follow the general convention. This kind of grouping is also very common with other applications/developers, e.g. everything from Adobe is in %LOCALAPPDATA%\Adobe, everything from Mozilla in %LOCALAPPDATA%\Joplin, everything from Microsoft under %LOCALAPPDATA%\Microsoft, etc.

1 Like