---

51.4.7 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. Emacs does the following things:

• 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 files, and if supported on your system, natively compile them too. This speeds up the execution of the code in the files when they are loaded. (see Byte Compilation in The Emacs Lisp Reference Manual.)
• 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 the The Emacs Initialization File 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.