4.6 User options

In Emacs, you normally set customizable variables (user options) using the M-x customize interface (see Easy Customization in GNU Emacs Manual). We recommend this method for most users. However, it is also possible to set them in your use-package declarations by using the :custom keyword.

(use-package comint
 :defer t
 :custom
 (comint-buffer-maximum-size 20000 "Increase comint buffer size.")
 (comint-prompt-read-only t "Make the prompt read only."))

This is better than using setq in a :config block, as customizable variables might have some code associated with it that Emacs will execute when you assign values to them. (In Emacs 29 and later, there is also the new setopt macro that does this for you.)

Note that the values customized using :custom are not saved in the standard Emacs custom-file (see Saving Customizations in GNU Emacs Manual). You should therefore set each user option using either the :custom keyword or M-x customize-option command; the latter will save customized values in the Emacs custom-file. Do not use both for the same variable, as this risks having conflicting values in your use-package declaration and your custom-file, which can lead to problems that are both tricky and tedious to debug.

Also note that if you use :custom in a file that you byte-compile, you could have some unexpected results if you later load or require use-package (e.g., due to lazy loading): the value of the corresponding user options could be reset back to their initial values. We therefore recommend against byte-compiling files that use use-package with :custom settings.

Next: Faces, Previous: Magic handlers, Up: Configuring Packages [Contents][Index]