When to specify a package name in use-package's :ensure tag?

Question

use-package lets you automatically install packages by using the :ensure tag. You can do that as follows

(use-package <package>
  :ensure t)

But for some packages that doesn't work, such as auctex. In those cases you can specify the package to ensure as follows

(use-package tex
  :ensure auctex)

According to this blog/tutorial/site, the reason is

because, once installed, auctex overrides the tex package.

What does that mean and how can I tell when to do that for other packages?

Answer 1

But for some packages that doesn't work. Such as auctex.

The reason (use-package tex :ensure t) doesn't work for auctex is because auctex names a GNU ELPA package (see (emacs) Packages), whereas tex names a feature (see (elisp) Named Features) provided by the auctex package.

In other words, tex names a single file tex.el which is distributed as part of the auctex package. Consider the following examples:

Typing M-xpp-macroexpand-last-sexpRET with point after

(use-package tex
  :ensure t)

gives a form which boils down to

(progn
  (use-package-ensure-elpa 'tex '(t) 'nil)
  (require 'tex nil t))

whereas doing the same with

(use-package tex
  :ensure auctex)

effectively expands to

(progn
  (use-package-ensure-elpa 'tex '(auctex) 'nil)
  (require 'tex nil t))

This illustrates the difference in purpose between the NAME argument to use-package and its :ensure keyword. The former declares which named feature the rest of the stanza pertains/defaults to, with exactly the same meaning as in with-eval-after-load; see (elisp) Hooks for Loading.

The latter just asks for the given package(s) to be installed via the second argument to the function use-package-ensure-elpa, where t just means the package named by the current NAME. use-package-ensure-elpa, in turn, calls package-install; for details on this see (emacs) Package Installation.

According to this blog/tutorial/site the reason is

because, once installed, auctex overrides the tex package.

What does that mean

Unfortunately, this is both wrong and misleading. "Overriding" usually refers to replacing or monkey-patching existing functionality, e.g. via advice. When one package provides the same named feature as another, thus hiding the latter from Emacs load functions, this is called "shadowing".

The AUCTeX distribution overrides and extends various built-in TeX-related functionality, but it does not shadow any built-in libraries. You can confirm this by inspecting the result of M-xlist-load-path-shadowsRET.

A better authority is the use-package documentation itself: https://github.com/jwiegley/use-package/#package-installation.

how can I tell when to do that for other packages?

It depends both on how you want to group your use-package stanzas and the name of the corresponding package. For example, if you want to put all or most of your Org-related settings under a single (use-package org ...), but want to use the org-plus-contrib distribution of Org instead of the built-in one, then you would write

(use-package org
  :ensure org-plus-contrib
  ...)

You wouldn't write

(use-package org-plus-contrib
  :ensure t
  ...)

because there is no file named org-plus-contrib.el, even if there is a package with the name org-plus-contrib. You similarly wouldn't write

(use-package auctex
  :ensure t
  ...)

for the same reason - there is no named feature auctex (there is a file auctex.el, but it does not call (provide 'auctex)).

---

Note that none of these discrepancies/semantics are specific to use-package; these are all (powerful and useful) Emacs features which use-package can only go so far in abstracting.