This module provides a terminal emulator powered by libvterm. It is still in alpha and requires a component be compiled (vterm-module.so).
vterm is as good as terminal emulation gets in Emacs (at the time of writing) and the most performant, as it is implemented in C. However, it requires extra steps to set up:
- Emacs must be built with dynamic modules support
- You must compile vterm-module.so, which has external dependencies (libvterm, cmake and libtool-bin).
vterm will try to automatically build vterm-module.so when you first open it, but this will fail on Windows, NixOS and Guix out of the box. Install instructions for nix/guix can be found in the :term vterm module’s documentation. There is no way to install vterm on Windows that I’m aware of (but perhaps with WSL?).
This module has no dedicated maintainers. Become a maintainer?
1.2. Module flags
This module has no flags.
No hacks documented for this module.
- Emacs must be built with dynamic module support, i.e. compiled with the
- You need libvterm installed on your system.
- You need make, cmake and a C compiler such as gcc so that vterm can build vterm-module.so.
2.1. Dynamic Module support
To check if your build of Emacs was built with dynamic module support, check
doom info for
MODULES in the “features” row. If it’s there, you’re good to
You can also check for --with-modules in the
variable (<help> v system-configuration-options).
- Archlinux or Manjaro users who installed Emacs through pacman will have support baked in.
- MacOS users:
- Ubuntu or Debian users:
$ apt-get install libvterm-dev
- ArchLinux or Manjaro:
$ pacman -S libvterm
$ brew install libvterm
systemPackages = with pkgs; [ # emacs # no need for this, the next line includes emacs ((emacsPackagesNgGen emacs).emacsWithPackages (epkgs: [ epkgs.vterm ])) ];
Or for home-manager users:
This already contains a version of vterm-module.so, so NixOS users need not compile the module themselves as described below.
Note: The nixpkgs-version that is used needs to be compatible with the rest of the plugins installed in doom. Therefore it might be necessary to pull in emacs and/or emacsPackagesNgGen from unstable or another channel. Otherwise arbitrary functionality of vterm might not work.
2.3. Compilation tools for vterm-module.so
When you first load vterm, it will compile vterm-module.so for you. For this to succeed, you need the following:
- A C compiler like gcc
- An internet connection (cmake will download needed libraries)
There are several ways to manually install the module:
You can use
M-x vterm-module-compileto let emacs automatically compile and install the module.
vterm-module-cmake-argsto pass arguments to the cmake build script. e.g. To use a local build of libvterm instead of the included one.
WARNING: Emacs will hang during the compilation. It may take a while.
You can compile and install the module yourself. Go to the vterm installation directory (usually ~/.emacs.d/.local/packages/elpa/vterm-<version>) and run the following:
- You can also compile vterm-module.so elsewhere, but the module must be moved/symlinked to ~/.emacs.d/.local/packages/elpa/vterm-<version>/vterm-module.so vterm-module.so. Keep in mind that this folder will be deleted whenever the vterm package is updated.
3. TODO Usage
The following commands are available to open it:
+vterm/toggle(<leader> t): Toggle vterm pop up window in the current project
+vterm/here(<leader> T): Opens vterm in the current window
4. TODO Configuration
This module has no configuration documentation yet. Write some?
There are no known problems with this module. Report one?
6. TODO Appendix
This module has no appendix yet. Write one?