Emacs Docs

Appearance

User Lisp Directory ​

If the directory specified by user-lisp-directory, defaulting to ~/.config/emacs/user-lisp/ or ~/.emacs.d/user-lisp/, exists, then at startup Emacs will prepare Lisp files within that directory for use in the session. Specifically, Emacs does the following:

  • Gather and activate autoload cookies. This means that you can use autoloaded commands and other entry points for the files in your user-lisp-directory without explicitly loading any of the files in your initialization file. See Autoload in The Emacs Lisp Reference Manual.
  • Byte-compile all the files (see Byte Compilation in The Emacs Lisp Reference Manual), and if supported by your build of Emacs, compile them to native code as well (see Native Compilation in The Emacs Lisp Reference Manual). This speeds up the execution of the code in those files when they are loaded and when they are executed later.
  • Adjust load-path such that all the files can be loaded and autoloaded in the usual ways. See Library Search in The Emacs Lisp Reference Manual.

The User Lisp directory is processed before loading your init file (see The Emacs Initialization File). Therefore any customizations to the user options discussed below must be made in your early init file (see The Early Init File) in order to have any effect.

By default, Emacs considers all Lisp files within user-lisp-directory, including within subdirectories. You can prevent Emacs from descending into specific subdirectories by customizing user-lisp-ignored-directories. You can completely disable scraping at startup by customizing user-lisp-auto-scrape to nil. In addition to how Emacs prepares the Lisp files automatically at startup, you can manually invoke preparation using the command prepare-user-lisp.

Although Emacs automatically handles recompilation when the contents of any Lisp files within the User Lisp directory have changed, there are other reasons why recompilation can become necessary that Emacs can’t autodetect. A good rule of thumb that will catch most (but not all) such issues is to force recompilation each time you upgrade to a new release of Emacs. Start the new version of Emacs, type C-u M-x prepare-user-lisp, then quit and restart Emacs again.

The User Lisp directory is a simpler mechanism than package installation (see Emacs Lisp Packages). In particular, there is no automatic dependency resolution or upgrading for files in the User Lisp directory, or any facility for building and registering package documentation. This means that usually the User Lisp directory is best for code you have written only for yourself. However, it is possible to use the User Lisp directory for third party packages or public packages you maintain.