Emacs Application Framework: Qt6 and Python Graphical Apps Inside Emacs

The Problem EAF Solves for Emacs Users

Emacs has been in active use for more than 45 years. Its extensibility through Emacs Lisp is its defining characteristic. However, Emacs Lisp lacks proper multithreading, and its graphical capabilities are restricted to what can be rendered with the toolkit Emacs was compiled against. The README summarizes the gap: Emacs cannot natively show a real browser, efficiently display a PDF, or play video without leaving the editor.

EAF addresses this by running applications as separate Python and Qt6 processes and embedding their output into Emacs buffers. The key insight is that Emacs does not need to render the graphical content itself; it only needs to display a frame from an external process and forward keyboard events to it. This means EAF can show anything Qt6 can render, without Emacs needing to understand the underlying graphical format.

The target user is an Emacs devotee who wants to stay in the editor for more of their workflow: reading PDFs, watching videos, browsing the web, managing files, taking notes with mind maps, and more, all within the Emacs keymap and configuration model.

How EAF Embeds Qt6 into Emacs Buffers

EAF's core is two files: eaf.el (the Emacs Lisp side) and eaf.py (the Python side). The Elisp component creates a buffer and communicates with the Python process over a local RPC mechanism. The Python process runs a Qt6 application that renders the graphical content and sends back rendered frames or input events.

This architecture means EAF applications are not Emacs Lisp plugins. They are Python programs with Qt6 UIs that happen to appear inside Emacs windows. Keybindings defined with eaf-bind-key route key events from Emacs to the running Qt6 application, allowing Emacs-style key sequences to control browser navigation, PDF scrolling, or other app-specific actions.

The application catalog is maintained separately from the core. Each application, such as eaf-browser, eaf-pdf-viewer, or eaf-music-player, is a separate repository under the emacs-eaf organization. The applications.json and dependencies.json files in the core repository define which apps are available and what they require.

Installing EAF: Clone, Script, and Elisp Configuration

Installation has five steps documented in the README. First, clone the repository:

git clone --depth=1 -b master https://github.com/emacs-eaf/emacs-application-framework.git ~/.emacs.d/site-lisp/emacs-application-framework/

Second, run the install script to fetch applications and Python dependencies:

cd emacs-application-framework
chmod +x ./install-eaf.py
./install-eaf.py

Alternatively, use M-x eaf-install-and-update from within Emacs once the core is loaded.

Third, add EAF to your Emacs load-path and require it in init.el:

(add-to-list 'load-path "~/.emacs.d/site-lisp/emacs-application-framework/")
(require 'eaf)

For use-package users, the README provides a sample configuration:

(use-package eaf
  :load-path "~/.emacs.d/site-lisp/emacs-application-framework"
  :custom
  (eaf-browser-continue-where-left-off t)
  (eaf-browser-enable-adblocker t)
  (browse-url-browser-function 'eaf-open-browser))

Fourth, load the specific application modules:

(require 'eaf-browser)
(require 'eaf-pdf-viewer)

The README notes that Nix, macOS, and Gentoo users must check the wiki before proceeding, as those platforms require extra steps not covered in the main README.

Applications Available in EAF

The README lists over fourteen applications in the EAF catalog. Notable ones include: a browser using a real web engine, described as modern and extensible; a PDF viewer described as the fastest PDF viewer in Emacs; a music player with playlist and audio visualization; a video player; an image viewer; an RSS reader; a full-featured terminal; a mind mapping tool (eaf-mind-elixir); a camera; Markdown and Org-mode previewers that update in real time; a multi-threaded git client; a file manager described as a multi-threaded replacement for dired-mode; and a basic video editor.

Each application is a separate install. The install-eaf.py script handles fetching them, and the --help flag documents available options. This separation means users who want only a PDF viewer do not need to install the browser or music player. It also means a bug in one application does not affect others.

EAF was presented at EmacsConf in both 2020 and 2021, which the README documents with links to the talks.

Limitations: Display Server Dependency and SSH Incompatibility

EAF requires a local graphical display. Qt6 renders to a screen; it cannot run in a headless terminal or over an SSH connection without additional X forwarding, which introduces latency. Engineers who work primarily on remote servers over SSH will find EAF impractical for daily use. The README states support for Linux X11, Windows, macOS, and FreeBSD, but does not mention Wayland. Users on Wayland-only setups should check the wiki before installing.

The Python and Qt6 dependency chain is substantial. The install script fetches per-application Python dependencies in addition to the Qt6 runtime. On a minimal system, this can add several hundred megabytes of packages. The README does not give a disk space estimate.

Application-specific keybinding configuration requires understanding how eaf-bind-key works. Unlike standard Emacs major-mode keybindings, EAF keybindings are routed to the Qt6 process rather than interpreted by Emacs directly. This means Emacs key inspection tools will not always reflect what a key does inside an EAF buffer.

EAF vs. Running a Separate Browser Window

The most natural comparison is simply running a browser window alongside Emacs in a tiling window manager. A separate browser window offers zero setup cost and full browser compatibility. EAF's trade-off is that the browser appears inside an Emacs buffer, meaning it participates in Emacs window management (splitting, switching, managing with perspective.el or similar tools) and its input can be bound to Emacs key sequences.

For users who organize their work entirely within Emacs using window configurations or workspaces, keeping a browser inside the editor avoids context-switching to a separate application and allows saving and restoring complete Emacs sessions that include browser state. For users who prefer their window manager to handle application switching, the separate window approach is simpler and more compatible.

VSCode, a commonly cited comparison for Emacs, takes the opposite architectural approach: it is built on a browser engine (Electron) and renders everything inside it. EAF inverts this by embedding browser-like rendering inside Emacs rather than embedding an editor inside a browser.

Editorial conclusion

EAF is worth installing for Emacs users who feel constrained by the editor's graphical limits and want a real browser, PDF reader, or video player without leaving Emacs. It is not suitable for users who primarily use Emacs on remote servers over SSH, since Qt6 requires a local display. The installation involves a Python script that installs multiple Qt6 dependencies and per-app packages, which adds significant disk space and complexity. Verify that your platform and display server are supported before investing in the setup; the wiki covers Nix, macOS, and Gentoo specifically as requiring additional steps. The last push was on 2026-08-23.

Frequently asked questions

Official sources

1. emacs-eaf/emacs-application-framework on GitHub
2. Issues
3. License: GPL-3.0
4. README