Emacs Lisp: require, load, load-file, autoload, feature, Explained

By Xah Lee. Date: . Last updated: .

This page explains emacs library system. For example, what's the difference between library, package, features? And what's the difference between {load-file, load, require, autoload}?

File/Package Loading Mechanisms

Emacs lisp's module system is a primitive system, centered on loading file, with some slightly high level things such as its {features, autoload, require}. However, nothing is strict or enforced by elisp.

Function NamePurposeTech DetailComment
load-fileLoad a specific file.Load one specific file. (“.el” or “.elc” file name extentions are not auto added, but “.gz” is.)Use this when you don't want emacs to guess the file name extention of “.el”, “.elc” or none.
loadLoad a file.Load a file by searching thru var load-path. Argument should be just the file name without full path, such as (load "undo"). It'll auto add “.elc” for compiled version if exist, or add “.el”, or with “.gz”.Use this if the exact file path is not known in advance.
requireLoad a package if it has not already been loaded.Checks the var features, if symbol is not there, then Alt+x load to load it. File name is guessed from the feature name, or specified in the optional argument.Best used in elisp libraries or scripts, similar to other lang's “require” or “import”.
autoloadLoad a file only when a function is called.Associate a function name with a file path. When the function is called, load the file, and execute the function.If you are writing a major mode, have your package installation go by autoload if possible. It saves startup time.

See also: Emacs Lisp: How to Name Your Major Mode.

What's Library, Package, Feature?

No Namespace

Emacs lisp the language does not have namespace. Everything is global, with dynamic scope, with some shadowing mechanism. So, don't expect library or module to be language defined namespace constructs like Perl or Python's module system or Java's Package system. (note: emacs 24 added lexical scoping for variables, using a directive. It must be specified in each file, and applies to that file's let only.)

What's the difference between a Package and Library?

These words are used losely, and do NOT have TECHNICAL definitions in elisp.

library → elisp file(s) containing a collection of useful stuff. For example, the command comment-dwim is defined in newcomment.el, which is a library of functions.

package → any useful elisp library for emacs users. For example: major mode or minor mode.

The term “module” is not used by emacs.

Emacs's Concept of Feature

Emacs Lisp: What's “feature”?

Package/Library/Feature are not Managed

There is no absolute relation between any concept of package/library/feature/autoload facilities and the file name.

By convention, if a elisp file name is xyz-mode.el, it OFTEN provides a lisp symbol “xyz-mode” as its feature name (if it does at all), and the command to invoke the mode is OFTEN named “xyz-mode”. Sometimes the “-mode” part is omitted in any of {file name, feature symbol name, command name}.

This is only a lose convention. There are a lot exceptions. For example:

All the above means, you could have a file named Joe-xyz-mode_v2.1.el, which provides a feature named “abc”, while the command name to activate it may be “opq”, and it might be displayed in mode line as “OPQ helper”. And, this file can be considered as a package or library.

Writing Major Mode Topics

  1. How to Write a Emacs Major Mode for Syntax Coloring
  2. Emacs Lisp: html6-mode
  3. Emacs Lisp: Font Lock Mode Basics
  4. Emacs Lisp: How to Define Face
  5. Emacs Lisp: How to Color Comment in Major Mode
  6. Emacs Lisp: How to Write Comment Command in Major Mode
  7. Emacs Lisp: How to Write Your Own Comment Command from Scratch
  8. Emacs Lisp: How to Write Keyword Completion Command
  9. Emacs Lisp: How to Create Keymap for Major Mode
  10. Emacs Lisp: Create Abbrev and Templates for Major Mode
  11. Emacs Lisp: Text Properties
  12. Emacs Lisp: Overlay Highlighting
  13. Emacs: Lookup Google, Dictionary, Documentation

  1. Emacs Lisp: How to Name Your Major Mode
  2. Emacs Lisp: What's “feature”?
  3. Emacs Lisp: require, load, load-file, autoload, feature, Explained

Syntax Table

  1. Emacs Lisp: Syntax Table Tutorial
  2. Emacs Lisp: How to Find Syntax of a Character?
  3. Emacs Lisp: How to Modify Syntax Table Temporarily
  4. Emacs Lisp: How to Determine If Cursor is Inside String or Comment
  5. Emacs Lisp: Find Matching Bracket Character
Like it? Buy Xah Emacs Tutorial. Thanks.