Diagnosing Emacs package.el Failures: Network, Archive, and Permission Checks

When M-x package-install hangs, reports failed to download, or silently returns without installing anything, the failure usually originates in one of four layers: network reachability, archive metadata, repository configuration, or local file permissions. This guide provides an ordered diagnostic path so you can identify the failing layer and apply the matching fix.

package.el is the package manager built into Emacs. It downloads a compressed index from configured archives (such as GNU ELPA), displays available packages, and installs them into a local directory—by default ~/.emacs.d/elpa. If any step in that chain breaks, installation fails.

Recognizable Symptoms

• package-refresh-contents finishes but package-list-packages shows no packages, or reports No packages found.
• The minibuffer or *Messages* buffer contains failed to download, Timeout, or connection refused.
• Refreshing contents produces package signature invalid or invalid signature.
• Installation stops with Unable to write to directory or Permission denied.
• Nothing appears in *Messages* at all, especially when Emacs runs in a terminal or with inhibit-startup-message enabled.

Cause and Diagnostic Reference

Finding	Likely Cause	First Diagnostic
Timeout or connection error in *Messages*	Network path to the archive host is blocked or down	curl -I <archive-url> from a shell
package signature invalid	Corrupted or outdated archive contents, or a mismatched signing key	Delete stale archive-contents files and refresh again
No packages listed after refresh	package-archives points to a non-existent, blocked, or mistyped URL	C-h v package-archives
Unable to write to directory	File-system permissions on ~/.emacs.d/elpa block your user	ls -ld ~/.emacs.d/elpa
No error output at all	Emacs started without a GUI or with inhibit-startup-message suppressing messages	Run M-x package-refresh-contents and immediately switch to *Messages*

Ordered Checks

Check 1: Capture the error in *Messages*

Run M-x package-refresh-contents. If the minibuffer flashes an error you cannot read, switch to the *Messages* buffer by pressing C-x b *Messages* RET. Look for lines containing package.el, gnu, melpa, or error. If the buffer is empty, the failure may be silent because Emacs is running in a terminal or with inhibit-startup-message set to t. In that case, run the command again from an interactive session or temporarily set inhibit-startup-message to nil in your init file.

Check 2: Inspect the archive list

Evaluate C-h v package-archives RET. The value should be an alist mapping archive names to URLs. A healthy default looks like:

(("gnu" . "https://elpa.gnu.org/packages/")
  ("nongnu" . "https://elpa.nongnu.org/nongnu/"))

If you see a typo, an http:// URL where https:// is required, or a hostname that no longer exists, that is the cause.

Check 3: Test reachability from a shell

Open a terminal and run:

curl -I https://elpa.gnu.org/packages/

You need normal user permissions. A successful response returns HTTP headers (for example, HTTP/2 200). If the command hangs, returns Connection refused, or produces a proxy error, the network path is the problem. If your environment requires a proxy, set url-proxy-services in Emacs or export http_proxy before launching Emacs.

Check 4: Examine ELPA directory permissions

Run the following in a shell:

ls -ld ~/.emacs.d/elpa

The output shows the owner, group, and permission bits. If the directory is owned by root or another user, or if the write bit is missing for your user, package.el cannot save downloaded files.

Fixes Tied to Findings

Fix A: Network timeout or connection refused

If curl cannot reach the archive, the issue is outside Emacs. Restore connectivity, adjust firewall rules, or configure a proxy. Once the shell command succeeds, retry M-x package-refresh-contents inside Emacs. If your shell requires a proxy, add the same setting to url-proxy-services:

(setq url-proxy-services
      '(("http" . "proxy.example.com:8080")
        ("https" . "proxy.example.com:8080")))

Replace proxy.example.com:8080 with your actual proxy host and port.

Fix B: Signature verification failure

When *Messages* reports package signature invalid, the downloaded archive-contents file may be stale or corrupted. Delete the cached contents and refresh:

1. Close Emacs.
2. In a shell, back up and remove the stale cache:

   mv ~/.emacs.d/elpa/archives ~/.emacs.d/elpa/archives.bak

3. Restart Emacs and run M-x package-refresh-contents.

Risk: Deleting the archives directory forces a full re-download of package metadata. Do not delete the entire ~/.emacs.d/elpa tree, because that removes installed packages and any local customizations inside them.

If the error persists on a third-party archive that does not sign its packages, you may need to relax signature checking. Set package-check-signatures to allow-unsigned rather than nil so that signed archives remain verified:

(setq package-check-signatures 'allow-unsigned)

Limitation: This setting trusts unsigned content from all configured archives. Only use it if you understand and accept that risk.

Fix C: Misconfigured package-archives

If C-h v package-archives shows a bad URL, correct it in your init file. For example, to restore the standard GNU and NonGNU ELPA entries:

(require 'package)
(setq package-archives
      '(("gnu" . "https://elpa.gnu.org/packages/")
        ("nongnu" . "https://elpa.nongnu.org/nongnu/")))
(package-initialize)

After evaluating the new value, run M-x package-refresh-contents again. If you added a third-party archive, confirm its URL with the archive maintainer before retrying.

Fix D: Permission denied on ~/.emacs.d/elpa

If ls -ld shows that your user cannot write to the directory, change ownership or permissions. Run the following in a shell, replacing youruser with your actual username:

sudo chown -R youruser:youruser ~/.emacs.d
chmod u+w ~/.emacs.d/elpa

Required permissions: chown typically requires sudo or root access. chmod requires that you own the file or directory. After fixing permissions, retry the installation.

Escalation Criteria

Seek further help when:

• The shell curl test succeeds, but Emacs still reports a timeout—this suggests an Emacs-specific proxy or TLS configuration issue.
• Signature errors persist after clearing the archive cache and confirming the archive URL with its maintainer.
• Permission fixes do not resolve write errors, which may indicate a read-only file system, SELinux policy, or disk-full condition.
• The failure occurs only in a specific Emacs build or version, pointing to a packaging bug rather than a local misconfiguration.

When escalating, include the exact text from *Messages*, the output of C-h v package-archives, the result of curl -I <archive-url>, and the ls -ld ~/.emacs.d/elpa output. That evidence lets helpers narrow the layer without guessing.

Verifying the Result

After applying a fix, confirm success by running M-x package-list-packages. If the package list populates without errors, select a small package and run M-x package-install. A successful installation adds the package under ~/.emacs.d/elpa and prints a completion message in *Messages*. If the list remains empty or the install fails again, return to the ordered checks above.