Introduction

Emacs-libvterm (vterm) is fully-fledged terminal emulator inside GNU Emacsbased on libvterm, a C library. As aresult of using compiled code (instead of elisp), emacs-libvterm is fullycapable, fast, and it can seamlessly handle large outputs.

Warning

This package is in active development and, while being stable enough to be usedas a daily-driver, it is currently in alpha stage. This means thatoccasionally the public interface will change (for example names of options orfunctions). A list of recent breaking changes is inappendix. Moreover, emacs-libvterm deals directly with somelow-level operations, hence, bugs can lead to segmentation faults and crashes.If that happens, please report theproblem.

Given that eshell, shell, and (ansi-)term are Emacs built-in, why should I use vterm?

The short answer is: unparalleled performance and compatibility with standardcommand-line tools.

For the long answer, let us discuss the differences between eshell, shell,term and vterm:

• eshell: it is a shell completely implemented in Emacs Lisp. It iswell-integrated in Emacs and it runs on Windows. It does not support command linetools that require terminal manipulation capabilities (e.g., ncdu, nmtui,...).
• shell: it interfaces with a standard shell (e.g., bash). It reads an inputfrom Emacs, sends it to the shell, and reports back the output from the shell.As such, like eshell, it does not support interactive commands, especiallythose that directly handle how the output should be displayed (e.g., htop).
• term: it is a terminal emulator written in elisp. term runs a shell(similarly to other terminal emulators like Gnome Terminal) and programs candirectly manipulate the output using escape codes. Hence, many interactiveapplications (like the one aforementioned) work with term. However, termand ansi-term do not implement all the escapes codes needed, so someprograms do not work properly. Moreover, term has inferior performancecompared to standalone terminals, especially with large bursts of output.
• vterm: like term it is a terminal emulator. Unlike term, the core ofvterm is an external library written in C, libvterm. For this reason,vterm outperforms term and has a nearly universal compatibility withterminal applications.

Vterm is not for you if you are using Windows, or if you cannot set up Emacswith support for modules. Otherwise, you should try vterm, as it provides asuperior terminal experience in Emacs.

Using vterm is like using Gnome Terminal inside Emacs: Vterm is fully-featuredand fast, but is not as well integrated in Emacs as eshell (yet), so some ofthe editing keybinding you are used to using may not work. For example,evil-mode is currently not supported (though, users can enable VI emulation intheir shells). This is because keys are sent directly to the shell. We areconstantly working to improve this.

Installation

Requirements

Before installing emacs-libvterm, you need to make sure you have installed

1. GNU Emacs (>= 25.1) with modulesupport.You can check that, by verifying that module-file-suffix is not nil.
2. cmake (>= 3.11)
3. libtool-bin (related issues:#66#85)
4. OPTIONAL: libvterm (>= 0.1). Thislibrary can be found in the official repositories of most distributions(e.g., Arch, Debian, Fedora, Gentoo, openSUSE, Ubuntu). Typical names arelibvterm (Arch, Fedora, Gentoo, openSUSE), or libvterm-dev (Debian,Ubuntu). If not available, libvterm will be downloaded during thecompilation process. Some distributions (e.g. Ubuntu < 20.04, Debian < 11)have versions of libvterm that are too old. If you find compilation errorsrelated to VTERM_COLOR, you should not use your system libvterm. SeeFAQ for more details.

From MELPA

vterm is available on MELPA, and it can be installed asa normal package. If the requirements are satisfied (mainly, Emacs was builtwith support for modules), vterm will compile the module the first time it isrun. This is the recommended way to install vterm.

vterm can be install from MELPA with use-package by adding the followinglines to your init.el:

(use-package vterm
    :ensure t)

To take full advantage of the capabilities of vterm, you should configure yourshell too. Read about this in the section shell-sideconfiguration.

Manual installation

Clone the repository:

git clone https://github.com/akermu/emacs-libvterm.git

By default, vterm will try to find if libvterm is installed. If it is not found,emacs-libvterm will download the latest version available of libvterm (fromhere), compile it, and use it. If youalways want to use the vendored version as opposed to the one on you system, setUSE_SYSTEM_LIBVTERM to no. To do this, change cmake .. with cmake -DUSE_SYSTEM_LIBVTERM=no .. in the following instructions.

Build the module with:

cd emacs-libvterm
mkdir -p build
cd build
cmake ..
make

And add this to your init.el:

(add-to-list 'load-path "path/to/emacs-libvterm")
(require 'vterm)

Or, with use-package:

(use-package vterm
  :load-path  "path/to/emacs-libvterm/")

vterm and Ubuntu

20.04

Using vterm on Ubuntu requires additional steps. The latest LTS version(20.04) ships without CMake installed and Emacs27 is not yet available from Ubuntu's package repository.

The basic steps for getting vterm to work on Ubuntu 20.04 are:

• Ensure Emacs27 is installed
• Install cmake, libtool, and libtool-bin

There are a few options for installing Emacs27 on Ubuntu 20.04:

• Compile Emacs27 from source
• Install Emacs27 from Snap
• Install Emacs27 from Kevin Kelley's PPA

In any case, if you have an older Emacs version you will need to purge it before proceeding:

Purge Emacs

sudo apt --purge remove emacs
sudo apt autoremove

Installing Emacs27 from Kevin Kelley PPA

sudo add-apt-repository ppa:kelleyk/emacs
sudo apt install emacs27

If you get an error about emacs27_common during the install process:

Errors were encountered while processing:
 /tmp/apt-dpkg-install-RVK8CA/064-emacs27-common_27.1~1.git86d8d76aa3-kk2+20.04_all.deb

run

sudo apt --purge remove emacs-common
sudo apt --fix-broken install

Installing Emacs27 from Snap

I hesitate to include SNAP here, because I ran into a number of GTK Theme parsing errors, and Fontconfig errors when I tested it, and reverted to installing from Kevin Kelley's PPA. YMMV

sudo snap install emacs --classic

Install CMake and Libtool

In Ubuntu 20.04 CMake (v3.16.3-1ubuntu1) and Libtool can be installed with

sudo apt install cmake
sudo apt install libtool
sudo apt install libtool-bin

18.04

Using vterm on Ubuntu 18.04 requires additional steps.18.04 ships with a version of CMake that is too old for vterm and GNUEmacs is not compiled with support for dynamical module loading.

It is possible to install GNU Emacs with module support from Kevin Kelley's PPA.The binary in Ubuntu Emacs Lisp PPA is currently broken and leads to segmentation faults(see #185).In case Emacs is already on the system, you need to purge it before proceedingwith the following commands.

sudo add-apt-repository ppa:kelleyk/emacs
sudo apt update
sudo apt-get install emacs26

A way to install a recent version of CMake (>= 3.11) is with linuxbrew.

brew install cmake

In some cases, /bin/sh needs to be relinked to /bin/bash for the compilationto work (see,#216).

Pull requests to improve support for Ubuntu are welcome (e.g., simplifying theinstallation).

Some releases of Ubuntu (e.g., 18.04) ship with a old version of libvterm thatcan lead to compilation errors. If you have this problem, see theFAQ for a solution.

GNU Guix

vterm and its dependencies are available in GNU Guix asemacs-vterm.The package can be installed with guix package -i emacs-vterm.

Shell-side configuration

Some of the most useful features in vterm (e.g., directory-tracking andprompt-tracking or messagepassing) require shell-side configurations. The main goal ofthese additional functions is to enable the shell to send information to vtermvia properly escaped sequences. A function that helps in this task,vterm_printf, is defined below. This function is widely used throughout thisreadme.

For bash or zsh, put this in your .zshrc or .bashrc

vterm_printf(){
    if [ -n "$TMUX" ] && ([ "${TERM%%-*}" = "tmux" ] || [ "${TERM%%-*}" = "screen" ] ); then
        # Tell tmux to pass the escape sequences through
        printf "\ePtmux;\e\e]%s\007\e\\" "$1"
    elif [ "${TERM%%-*}" = "screen" ]; then
        # GNU screen (screen, screen-256color, screen-256color-bce)
        printf "\eP\e]%s\007\e\\" "$1"
    else
        printf "\e]%s\e\\" "$1"
    fi
}

This works also for dash.

For fish put this in your ~/.config/fish/config.fish:

function vterm_printf;
    if begin; [  -n "$TMUX" ]  ; and  string match -q -r "screen|tmux" "$TERM"; end 
        # tell tmux to pass the escape sequences through
        printf "\ePtmux;\e\e]%s\007\e\\" "$argv"
    else if string match -q -- "screen*" "$TERM"
        # GNU screen (screen, screen-256color, screen-256color-bce)
        printf "\eP\e]%s\007\e\\" "$argv"
    else
        printf "\e]%s\e\\" "$argv"
    end
end

Debugging and testing

If you have successfully built the module, you can test it by executing thefollowing command in the build directory:

make run

Usage

vterm

Open a terminal in the current window.

vterm-other-window

Open a terminal in another window.

vterm-copy-mode

When you enable vterm-copy-mode, the terminal buffer behaves like a normalread-only text buffer: you can search, copy text, etc. The default keybindingto toggle vterm-copy-mode is C-c C-t. When a region is selected, it ispossible to copy the text and leave vterm-copy-mode with the enter key.

If no region is selected when the enter key is pressed it will copy the currentline from start to end. If vterm-copy-exclude-prompt is true it will skipthe prompt and not include it in the copy.

vterm-clear-scrollback

vterm-clear-scrollback does exactly what the name suggests: it clears thecurrent buffer from the data that it is not currently visible.vterm-clear-scrollback is bound to C-c C-l. This function is typically usedwith the clear function provided by the shell to clear both screen andscrollback. In order to achieve this behavior, you need to add a new shell alias.

For zsh, put this in your .zshrc:

if [[ "$INSIDE_EMACS" = 'vterm' ]]; then
    alias clear='vterm_printf "51;Evterm-clear-scrollback";tput clear'
fi

For bash, put this in your .bashrc:

if [[ "$INSIDE_EMACS" = 'vterm' ]]; then
    function clear(){
        vterm_printf "51;Evterm-clear-scrollback";
        tput clear;
    }
fi

For fish:

if [ "$INSIDE_EMACS" = 'vterm' ]
    function clear
        vterm_printf "51;Evterm-clear-scrollback";
        tput clear;
    end
end

These aliases take advantage of the fact that vterm can execute elispcommands, as explained below.

If it possible to automatically clear the scrollback when the screen is clearedby setting the variable vterm-clear-scrollback-when-clearing: Whenvterm-clear-scrollback-when-clearing is non nil, C-l clears both the screenand the scrollback. When is nil, C-l only clears the screen. The oppositebehavior can be achieved by using the universal prefix (i.e., calling C-u C-l).

Customization

vterm-shell

Shell to run in a new vterm. It defaults to $SHELL.

vterm-environment

to add more environment variables there is the custom vterm-environment which hasa similar format than the internal Emacs variable process-environment.You can check the documentation with C-h v process-environment for more details.

vterm-term-environment-variable

Value for the TERM environment variable. It defaults to xterm-256color. Ifeterm-256color is installed,setting vterm-term-environment-variable to eterm-color improves therendering of colors in some systems.

vterm-kill-buffer-on-exit

If set to t, buffers are killed when the associated process is terminated (forexample, by logging out the shell). Keeping buffers around it is useful if youneed to copy or manipulate the content.

vterm-module-cmake-args

Compilation flags and arguments to be given to CMake when compiling the module.This string is directly passed to CMake, so it uses the same syntax. At themoment, it main use is for compiling vterm using the system libvterm instead ofthe one downloaded from GitHub. You can find all the arguments and flagsavailable with cmake -LA in the build directory.

vterm-copy-exclude-prompt

Controls whether or not to exclude the prompt when copying a line invterm-copy-mode. Using the universal prefix before callingvterm-copy-mode-done will invert the value for that call, allowing you totemporarily override the setting. When a prompt is not found, the whole line iscopied.

vterm-use-vterm-prompt-detection-method

The variable vterm-use-vterm-prompt-detection-method determines whether to usethe vterm prompt tracking, if false it use the regexp invterm-copy-prompt-regexp to search for the prompt.

vterm-enable-manipulate-selection-data-by-osc52

Vterm support copy text to Emacs kill ring and system clipboard by using OSC 52.See https://invisible-island.net/xterm/ctlseqs/ctlseqs.html for more info about OSC 52.For example: send 'blabla' to kill ring: printf "\033]52;c;$(printf "%s" "blabla" | base64)\a"

tmux can share its copy buffer to terminals by supporting osc52(like iterm2 xterm),you can enable this feature for tmux by :set -g set-clipboard on #osc 52 copy paste share with itermset -ga terminal-overrides ',xterm*:XT:Ms=\E]52;%p1%s;%p2%s\007'set -ga terminal-overrides ',screen*:XT:Ms=\E]52;%p1%s;%p2%s\007'

The clipboard querying/clearing functionality offered by OSC 52 is not implemented here,And for security reason, this feature is disabled by default."

This feature need the new way of handling strings with a struct VTermStringFragmentin libvterm. You'd better compile emacs-libvterm with cmake -DUSE_SYSTEM_LIBVTERM=no ...If you don't do that, when the content you want to copied is too long, it would be truncatedby bug of libvterm.

vterm-buffer-name-string

When vterm-buffer-name-string is not nil, vterm renames automatically its ownbuffers with vterm-buffer-name-string. This string can contain the character%s, which is substituted with the title (as defined by the shell, seebelow). A possible value for vterm-buffer-name-string is vterm %s, accordingto which all the vterm buffers will be named "vterm TITLE".

This requires some shell-side configuration to print the title. For example toset the name "HOSTNAME:PWD", use can you the following:

For zsh

autoload -U add-zsh-hook
add-zsh-hook -Uz chpwd (){ print -Pn "\e]2;%m:%2~\a" }

For bash,

PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND; }"'echo -ne "\033]0;${HOSTNAME}:${PWD}\007"'

For fish,

function fish_title
    hostname
    echo ":"
    pwd
end

See zsh and bash and fishdocumentations.

vterm-always-compile-module

Vterm needs vterm-module to work. This can be compiled externally, or vtermwill ask the user whether to build the module when vterm is first called. Toavoid this question and always compile the module, setvterm-always-compile-module to t.

Keybindings

If you want a key to be sent to the terminal, bind it to vterm--self-insert,or remove it from vterm-mode-map. By default, vterm.el binds most of theC-<char> and M-<char> keys, <f1> through <f12> and some special keyslike <backspace> and <return>. Sending a keyboard interrupt is bound to C-c C-c.

Fonts

You can change the font (the face) used in a vterm with the following code:

(add-hook 'vterm-mode-hook
          (lambda ()
            (set (make-local-variable 'buffer-face-mode-face) 'fixed-pitch)
                 (buffer-face-mode t)))

Where instead of 'fixed-pitch you specify the face you want to use. Theexample reported here can be used to force vterm to use a mono-spaced font (thefixed-pitch face). This is useful when your default font in Emacs is aproportional font.

In addition to that, you can disable some text properties (bold, underline,reverse video) setting the relative option to t (vterm-disable-bold,vterm-disable-underline, or vterm-disable-inverse-video).

Blink cursor

When vterm-ignore-blink-cursor is t, vterm will ignore request from application to turn on or off cursor blink.

If nil, cursor in any window may begin to blink or not blink because blink-cursor-modeis a global minor mode in Emacs, you can use M-x blink-cursor-mode to toggle.

Colors

Set the :foreground and :background attributes of the following faces to acolor you like. The :foreground is ansi color 0-7, the :background attributeis ansi color 8-15.

• vterm-color-black
• vterm-color-red
• vterm-color-green
• vterm-color-yellow
• vterm-color-blue
• vterm-color-magenta
• vterm-color-cyan
• vterm-color-white

Directory tracking and Prompt tracking

vterm supports directory tracking. If this feature is enabled, the defaultdirectory in Emacs and the current working directory in vterm are synced. As aresult, interactive functions that ask for a path or a file (e.g., dired orfind-file) will do so starting from the current location.

And vterm supports prompt tracking. If this feature is enabled, Emacs knowswhere the prompt ends, you needn't customize term-prompt-regexp any more.Then you can use vterm-next-prompt and vterm-previous-promptmoving to end of next/previous prompt. The default keybinding is C-c C-n and C-c C-p.

And vterm-beginning-of-line would move the point to the first character after theshell prompt on this line. If the point is already there, move to the beginning of the line.The default keybinding is C-a in vterm-copy-mode.

And vterm--at-prompt-p would check whether the cursor is at the point just afterthe shell prompt.

Directory tracking and Prompt tracking requires some configuration, as the shell has to beinstructed to share the relevant information with Emacs. The following pieces ofcode assume that you have the function vterm_printf as defined in sectionshell-side configuration.

For zsh, put this at the end of your .zshrc:

vterm_prompt_end() {
    vterm_printf "51;A$(whoami)@$(hostname):$(pwd)";
}
setopt PROMPT_SUBST
PROMPT=$PROMPT'%{$(vterm_prompt_end)%}'

For bash, put this at the end of your .bashrc:

vterm_prompt_end(){
    vterm_printf "51;A$(whoami)@$(hostname):$(pwd)"
}
PS1=$PS1'\[$(vterm_prompt_end)\]'

For fish, put this in your ~/.config/fish/config.fish:

function vterm_prompt_end;
    vterm_printf '51;A'(whoami)'@'(hostname)':'(pwd)
end
functions --copy fish_prompt vterm_old_fish_prompt
function fish_prompt --description 'Write out the prompt; do not replace this. Instead, put this at end of your file.'
    # Remove the trailing newline from the original prompt. This is done
    # using the string builtin from fish, but to make sure any escape codes
    # are correctly interpreted, use %b for printf.
    printf "%b" (string join "\n" (vterm_old_fish_prompt))
    vterm_prompt_end
end

Here we are using the function vterm_printf that we have discussed above, so makesure that this function is defined in your configuration file.

Directory tracking works on remote servers too. In case the hostname of yourremote machine does not match the actual hostname needed to connect to thatserver, change $(hostname) with the correct one. For example, if the correcthostname is foo and the username is bar, you should have something like

HOSTNAME=foo
USER=baz
vterm_printf "51;A$USER@$HOSTNAME:$(pwd)"

Message passing

vterm can read and execute commands. At the moment, a command ispassed by providing a specific escape sequence. For example, to evaluate

(message "Hello!")

use

printf "\e]51;Emessage \"Hello\!\"\e\\"
# or
vterm_printf "51;Emessage \"Hello\!\""

The commands that are understood are defined in the setting vterm-eval-cmds.

As split-string-and-unquote is used the parse the passed string, double quotesand backslashes need to be escaped via backslash. A convenient shell function toautomate the substitution is

bash or zsh:

vterm_cmd() {
    local vterm_elisp
    vterm_elisp=""
    while [ $# -gt 0 ]; do
        vterm_elisp="$vterm_elisp""$(printf '"%s" ' "$(printf "%s" "$1" | sed -e 's|\\|\\\\|g' -e 's|"|\\"|g')")"
        shift
    done
    vterm_printf "51;E$vterm_elisp"
}

fish:

function vterm_cmd --description 'Run an Emacs command among the ones been defined in vterm-eval-cmds.'
    set -l vterm_elisp ()
    for arg in $argv
        set -a vterm_elisp (printf '"%s" ' (string replace -a -r '([\\\\"])' '\\\\\\\\$1' $arg))
    end
    vterm_printf '51;E'(string join '' $vterm_elisp)
end

Now we can write shell functions to call the ones defined in vterm-eval-cmds.

find_file() {
    vterm_cmd find-file "$(realpath "${@:-.}")"
}

say() {
    vterm_cmd message "%s" "$*"
}

Or for fish:

function find_file
    set -q argv[1]; or set argv[1] "."
    vterm_cmd find-file (realpath "$argv")
end

function say
    vterm_cmd message "%s" "$argv"
end

This newly defined find_file function can now be used inside vterm as

find_file name_of_file_in_local_directory

If you call find_file without specifying any file (you just execute find_file in your shell),dired will open with the current directory.

As an example, say you like having files opened below the current window. Youcould add the command to do it on the lisp side like so:

(push (list "find-file-below"
            (lambda (path)
              (if-let* ((buf (find-file-noselect path))
                        (window (display-buffer-below-selected buf nil)))
                  (select-window window)
                (message "Failed to open file: %s" path))))
      vterm-eval-cmds)

Then add the command in your .bashrc file.

open_file_below() {
    vterm_cmd find-file-below "$(realpath "${@:-.}")"
}

Then you can open any file from inside your shell.

open_file_below ~/Documents

Shell-side configuration files

The configurations described in earlier sections are combined inetc/. These can be appended to or loaded into your userconfiguration file. Alternatively, they can be installed system-wide, forexample in /etc/bash/bashrc.d/, /etc/profile.d/ (for zsh), or/etc/fish/conf.d/ for fish.

When using vterm Emacs sets the environment variable INSIDE_EMACS in the subshell to ‘vterm’.Usually the programs check this variable to determine whether they are running inside Emacs.

Vterm also sets an extra variable EMACS_VTERM_PATH to the place where the vterm library is installed.This is very useful because when vterm is installed from melpa the Shell-side configuration files arein the EMACS_VTERM_PATH inside the /etc sub-directory. After a package update, the directory name changes,so, a code like this in your bashrc could be enough to load always the latest version of the filefrom the right location without coping any file manually.

if [[ "$INSIDE_EMACS" = 'vterm' ]] \
    && [[ -n ${EMACS_VTERM_PATH} ]] \
    && [[ -f ${EMACS_VTERM_PATH}/etc/emacs-vterm-bash.sh ]]; then
	source ${EMACS_VTERM_PATH}/etc/emacs-vterm-bash.sh
fi

Frequently Asked Questions and Problems

How can I increase the size of the scrollback?

By default, the scrollback can contain up to 1000 lines per each vterm buffer.You can increase this up to 100000 by changing the variablevterm-max-scrollback. If you want to increase it further, you have to edit thefile vterm-module.h, change the variable SB_MAX, and set the new value forvterm-max-scrollback. The potential maximum memory consumption of vtermbuffers increases with vterm-max-scrollback, so setting SB_MAX to extremevalues may lead to system instabilities and crashes.

How can I automatically close vterm buffers when the process is terminated?

There is an option for that: set vterm-kill-buffer-on-exit to t.

The package does not compile, I have errors related to VTERM_COLOR.

The version of libvterm installed on your system is too old. You should letemacs-libvterm download libvterm for you. You can either uninstall yourlibvterm, or instruct Emacs to ignore the system libvterm. If you are compilingfrom Emacs, you can do this by setting:

(setq vterm-module-cmake-args "-DUSE_SYSTEM_LIBVTERM=no")

and compile again. If you are compiling with CMake, use the flag-DUSE_SYSTEM_LIBVTERM=no.

<C-backspace> doesn't kill previous word.

This can be fixed by rebinding the key to what C-w does:

(define-key vterm-mode-map (kbd "<C-backspace>")
    (lambda () (interactive) (vterm-send-key (kbd "C-w"))))

counsel-yank-pop doesn't work.

Add this piece of code to your configuration file to make counsel usethe correct function to yank in vterm buffers.

(defun vterm-counsel-yank-pop-action (orig-fun &rest args)
  (if (equal major-mode 'vterm-mode)
      (let ((inhibit-read-only t)
            (yank-undo-function (lambda (_start _end) (vterm-undo))))
        (cl-letf (((symbol-function 'insert-for-yank)
               (lambda (str) (vterm-send-string str t))))
            (apply orig-fun args)))
    (apply orig-fun args)))

(advice-add 'counsel-yank-pop-action :around #'vterm-counsel-yank-pop-action)

How can I get the local directory without shell-side configuration?

We recommend that you set up shell-side configuration for reliable directorytracking. If you cannot do it, a possible workaround is the following.

On most GNU/Linux systems, you can read current directory from /proc:

(defun vterm-directory-sync ()
  "Synchronize current working directory."
  (interactive)
  (when vterm--process
    (let* ((pid (process-id vterm--process))
           (dir (file-truename (format "/proc/%d/cwd/" pid))))
      (setq default-directory dir))))

A possible application of this function is in combination with find-file:

(advice-add #'find-file :before #'vterm-directory-sync)

This method does not work on remote machines.

How can I get the directory tracking in a more understandable way?

If you looked at the recommended way to set-up directory tracking, you will havenoticed that it requires printing obscure code like \e]2;%m:%2~\a (unless youare using fish).

There is another way to achieve this behavior. Define a shell function, on alocal host you can simply use

vterm_set_directory() {
    vterm_cmd update-pwd "$PWD/"
}

On a remote one, use instead

vterm_set_directory() {
    vterm_cmd update-pwd "/-:""$USER""@""$HOSTNAME"":""$PWD/"
}

Then, for zsh, add this function to the chpwd hook:

autoload -U add-zsh-hook
add-zsh-hook -Uz chpwd (){ vterm_set_directory }

For bash, append it to the prompt:

PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND; }vterm_set_directory"

Finally, add update-pwd to the list of commands that Emacsis allowed to execute from vterm:

(add-to-list 'vterm-eval-cmds '("update-pwd" (lambda (path) (setq default-directory path))))

When evil-mode is enabled, the cursor moves back in normal state, and this messes directory tracking

evil-collection provides a solution for this problem. If you do not want touse evil-collection, you can add the following code:

(defun evil-collection-vterm-escape-stay ()
"Go back to normal state but don't move
cursor backwards. Moving cursor backwards is the default vim behavior but it is
not appropriate in some cases like terminals."
(setq-local evil-move-cursor-back nil))

(add-hook 'vterm-mode-hook #'evil-collection-vterm-escape-stay)

Related packages

• vterm-toggle: Toggles between avterm and the current buffer
• multi-libvterm: Multiterm for emacs-libvterm

Appendix

Breaking changes

Obsolete variables will be removed in version 0.1.

October 2020

• vterm-disable-bold-font was renamed to vterm-disable-bold to uniform itwith the other similar options.

July 2020

• vterm-use-vterm-prompt was renamed to vterm-use-vterm-prompt-detection-method.
• vterm-kill-buffer-on-exit is set to t by default.

April 2020

• vterm-clear-scrollback was renamed to vterm-clear-scrollback-when-clearning.
• vterm-set-title-functions was removed. In its place, there is a new customoption vterm-buffer-name-string. Seevterm-buffer-name-string for documentation.