Quick links: help overview · quick reference · user manual toc · reference manual toc · faq
terminal.txt  For Vim version 8.0.  Last change: 2018 Mar 16

                  VIM REFERENCE MANUAL    by Bram Moolenaar

Terminal window support                                 terminal

The terminal feature is optional, use this to check if your Vim has it: 
        echo has('terminal')
If the result is "1" you have it.

1. Basic use                    terminal-use
      Typing                            terminal-typing
      Size and color                    terminal-size-color
      Syntax                            :terminal
      Resizing                          terminal-resizing
      Terminal Modes                    Terminal-mode
      Cursor style                      terminal-cursor-style
      Special keys                      terminal-special-keys
      Session                           terminal-session
      Unix                              terminal-unix
      MS-Windows                        terminal-ms-windows
2. Remote testing               terminal-testing
3. Diffing screen dumps         terminal-diff
      Writing a screen dump test for Vim  terminal-dumptest
      Creating a screen dump              terminal-screendump
      Comparing screen dumps              terminal-diffscreendump
4. Debugging                    terminal-debug
      Starting                          termdebug-starting
      Example session                   termdebug-example
      Stepping through code             termdebug-stepping
      Inspecting variables              termdebug-variables
      Other commands                    termdebug-commands
      Communication                     termdebug-communication
      Customizing                       termdebug-customizing

{Vi does not have any of these commands}
{only available when compiled with the |+terminal| feature}
The terminal feature requires the +multi_byte, +job and +channel features.

1. Basic use                                            terminal-use

This feature is for running a terminal emulator in a Vim window.  A job can be
started connected to the terminal emulator. For example, to run a shell: 
     :term bash

Or to run build command: 
     :term make myprogram

The job runs asynchronously from Vim, the window will be updated to show
output from the job, also while editing in another window.

When the keyboard focus is in the terminal window, typed keys will be sent to
the job.  This uses a pty when possible.  You can click outside of the
terminal window to move keyboard focus elsewhere.

CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
        CTRL-W CTRL-W   move focus to the next window
        CTRL-W :        enter an Ex command
See CTRL-W for more commands.

Special in the terminal window:                 CTRL-W_.  CTRL-W_N 
        CTRL-W .        send a CTRL-W to the job in the terminal
        CTRL-W N        go to Terminal-Normal mode, see Terminal-mode
        CTRL-\ CTRL-N   go to Terminal-Normal mode, see Terminal-mode
        CTRL-W " {reg}  paste register {reg}            CTRL-W_quote
                        Also works with the = register to insert the result of
                        evaluating an expression.
        CTRL-W CTRL-C   ends the job, see below t_CTRL-W_CTRL-C

See option 'termkey' for specifying another key instead of CTRL-W that
will work like CTRL-W.  However, typing 'termkey' twice sends 'termkey' to
the job.  For example:
        'termkey' CTRL-W    move focus to the next window
        'termkey' :         enter an Ex command
        'termkey' 'termkey' send 'termkey' to the job in the terminal
        'termkey' .         send a CTRL-W to the job in the terminal
        'termkey' N         go to terminal Normal mode, see below
        'termkey' CTRL-N    same as CTRL-W N
        'termkey' CTRL-C    same as t_CTRL-W_CTRL-C
The special key combination CTRL-\ CTRL-N can be used to switch to Normal
mode, just like this works in any other mode.
CTRL-W CTRL-C can be typed to forcefully end the job.  On MS-Windows a
CTRL-BREAK will also kill the job.

If you type CTRL-C the effect depends on what the pty has been configured to
do.  For simple commands this causes a SIGINT to be sent to the job, which
would end it.  Other commands may ignore the SIGINT or handle the CTRL-C
themselves (like Vim does).

To change the keys you type use terminal mode mappings, see :tmap.
These are defined like any mapping, but apply only when typing keys that are
sent to the job running in the terminal.  For example, to make F1 switch
to Terminal-Normal mode: 
   tnoremap <F1> <C-W>N
You can use Esc, but you need to make sure it won't cause other keys to
   tnoremap <Esc> <C-W>N
   set notimeout ttimeout timeoutlen=100

After opening the terminal window and setting 'buftype' to "terminal" the
BufWinEnter autocommand event is triggered.  This makes it possible to set
options specifically for the window and buffer.  Example: 
   au BufWinEnter * if &buftype == 'terminal' | setlocal bufhidden=hide | endif

Mouse events (click and drag) are passed to the terminal.  Mouse move events
are only passed when Vim itself is receiving them.  For a terminal that is
when 'balloonevalterm' is enabled.

Size and color 
See option 'termsize' for controlling the size of the terminal window.
(TODO: scrolling when the terminal is larger than the window)

The job running in the terminal can change the colors.  The default foreground
and background colors are taken from Vim, the Normal highlight group.

For a color terminal the 'background' option is used to decide whether the
terminal window will start with a white or black background.

To use a different color the Terminal highlight group can be used, for
    hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue


:[range]ter[minal] [options] [command]                  :ter :terminal
                        Open a new terminal window.

                        If [command] is provided run it as a job and connect
                        the input and output to the terminal.
                        If [command] is not given the 'shell' option is used.
                        if [command] is NONE no job is started, the pty of the
                        terminal can be used by a command like gdb.

                        If [command] is missing the default behavior is to
                        close the terminal when the shell exits.  This can be
                        changed with the ++noclose argument.
                        If [command] is present the default behavior is to
                        keep the terminal open in Terminal-Normal mode.  This
                        can be changed with the ++close argument.

                        A new buffer will be created, using [command] or
                        'shell' as the name, prefixed with a "!".  If a buffer
                        by this name already exists a number is added in
                        parentheses.  E.g. if "gdb" exists the second terminal
                        buffer will use "!gdb (1)".

                        If [range] is given the specified lines are used as
                        input for the job.  It will not be possible to type
                        keys in the terminal window.  For MS-Windows see the
                        ++eof argument below.

                                                term++close term++open
                        Supported [options] are:
                        ++close         The terminal window will close
                                        automatically when the job terminates.
                        ++noclose       The terminal window will NOT close
                                        automatically when the job terminates.
                        ++open          When the job terminates and no window
                                        shows it, a window will be opened.
                                        Note that this can be interruptive.
                                The last of ++close, ++noclose and ++open
                                matters and rules out earlier arguments.

                        ++curwin        Open the terminal in the current
                                        window, do not split the current
                                        window.  Fails if the current buffer
                                        cannot be abandoned.
                        ++hidden        Open the terminal in a hidden buffer,
                                        no window will be used.
                        ++norestore     Do not include this terminal window
                                        in a session file.
                        ++kill={how}    When trying to close the terminal
                                        window kill the job with {how}.  See
                                        term_setkill() for the values.
                        ++rows={height} Use {height} for the terminal window
                                        height.  If the terminal uses the full
                                        Vim height (no window above or below
                                        th terminal window) the command line
                                        height will be reduced as needed.
                        ++cols={width}  Use {width} for the terminal window
                                        width. If the terminal uses the full
                                        Vim width (no window left or right of
                                        the terminal window) this value is
                        ++eof={text}    when using [range]: text to send after
                                        the last line was written. Cannot
                                        contain white space.  A CR is
                                        appended.  For MS-Windows the default
                                        is to send CTRL-D.
                                        E.g. for a shell use "++eof=exit" and
                                        for Python "++eof=exit()".  Special
                                        codes can be used like with :map,
                                        e.g. "<C-Z>" for CTRL-Z.

                        If you want to use more options use the term_start()

When the buffer associated with the terminal is forcibly unloaded or wiped out
the job is killed, similar to calling `job_stop(job, "kill")` .
Closing the window normally results in E947.  When a kill method was set
with "++kill={how}" or term_setkill() then closing the window will use that
way to kill or interrupt the job.  For example: 
        :term ++kill=term tail -f /tmp/log

So long as the job is running the window behaves like it contains a modified
buffer.  Trying to close the window with `CTRL-W :quit` fails.  When using
`CTRL-W :quit!` the job is ended.  The text in the window is lost.  The buffer
still exists, but getting it in a window with :buffer will show an empty

Trying to close the window with `CTRL-W :close` also fails.   Using
`CTRL-W :close!` will close the window and make the buffer hidden.

You can use `CTRL-W :hide` to close the terminal window and make the buffer
hidden, the job keeps running.  The :buffer command can be used to turn the
current window into a terminal window.  If there are unsaved changes this
fails, use !  to force, as usual.

To have a background job run without a window, and open the window when it's
done, use options like this: 
        :term ++hidden ++open make
Note that the window will open at an unexpected moment, this will interrupt
what you are doing.

                                                        E947 E948
So long as the job is running, the buffer is considered modified and Vim
cannot be quit easily, see abandon.

When the job has finished and no changes were made to the buffer: closing the
window will wipe out the buffer.

Before changes can be made to a terminal buffer, the 'modifiable' option must
be set.  This is only possible when the job has finished.  At the first change
the buffer will become a normal buffer and the highlighting is removed.
You may want to change the buffer name with :file to be able to write, since
the buffer name will still be set to the command.

The size of the terminal can be in one of three modes:

1. The 'termsize' option is empty: The terminal size follows the window size.
   The minimal size is 2 screen lines with 10 cells.

2. The 'termsize' option is "rows*cols", where "rows" is the minimal number of
   screen rows and "cols" is the minimal number of cells.

3. The 'termsize' option is "rowsXcols" (where the x is upper or lower case).
   The terminal size is fixed to the specified number of screen lines and
   cells.  If the window is bigger there will be unused empty space.

If the window is smaller than the terminal size, only part of the terminal can
be seen (the lower-left part).

The term_getsize() function can be used to get the current size of the
terminal.  term_setsize() can be used only when in the first or second mode,
not when 'termsize' is "rowsXcols".

Terminal-Job and Terminal-Normal mode 
When the job is running the contents of the terminal is under control of the
job.  That includes the cursor position.  Typed keys are sent to the job.
The terminal contents can change at any time.  This is called Terminal-Job

Use CTRL-W N (or 'termkey' N) to switch to Terminal-Normal mode.  Now the
contents of the terminal window is under control of Vim, the job output is
suspended.  CTRL-\ CTRL-N does the same.

Terminal-Job mode is where :tmap mappings are applied. Keys sent by
term_sendkeys() are not subject to tmap, but keys from feedkeys() are.

In Terminal-Normal mode you can move the cursor around with the usual Vim
commands, Visually mark text, yank text, etc.  But you cannot change the
contents of the buffer.  The commands that would start insert mode, such as
'i' and 'a', return to Terminal-Job mode.  The window will be updated to show
the contents of the terminal. :startinsert is ineffective.

In Terminal-Normal mode the statusline and window title show "(Terminal)".  If
the job ends while in Terminal-Normal mode this changes to

It is not possible to enter Insert mode from Terminal-Job mode.

Cursor style 
By default the cursor in the terminal window uses a not blinking block.  The
normal xterm escape sequences can be used to change the blinking state and the
shape.  Once focus leaves the terminal window Vim will restore the original

An exception is when xterm is started with the "-bc" argument, or another way
that causes the cursor to blink.  This actually means that the blinking flag
is inverted.  Since Vim cannot detect this, the terminal window cursor
blinking will also be inverted.

A terminal window will be restored when using a session file, if possible and

If "terminal" was removed from 'sessionoptions' then no terminal windows will
be restored.

If the job in the terminal was finished the window will not be restored.

If the terminal can be restored, the command that was used to open it will be
used again.  To change this use the term_setrestore() function.  This can
also be used to not restore a specific terminal by setting the command to

Special keys 
Since the terminal emulator simulates an xterm, only escape sequences that
both Vim and xterm recognize will be available in the terminal window.  If you
want to pass on other escape sequences to the job running in the terminal you
need to set up forwarding.  Example: 
        tmap <expr> <Esc>]b SendToTerm("\<Esc>]b")
        func SendToTerm(what)
          call term_sendkeys('', a:what)
          return ''

On Unix a pty is used to make it possible to run all kinds of commands.  You
can even run Vim in the terminal!  That's used for debugging, see below.

Environment variables are used to pass information to the running job:
    TERM                name of the terminal, 'term'
    ROWS                number of rows in the terminal initially
    LINES               same as ROWS
    COLUMNS             number of columns in the terminal initially
    COLORS              number of colors, 't_Co' (256*256*256 in the GUI)
    VIM_SERVERNAME      v:servername

The client-server feature can be used to communicate with the Vim instance
where the job was started.  This only works when v:servername is not empty.
If needed you can set it with: 
        call remote_startserver('vim-server')

In the job you can then do something like: 
        vim --servername $VIM_SERVERNAME --remote +123 some_file.c
This will open the file "some_file.c" and put the cursor on line 123.

On MS-Windows winpty is used to make it possible to run all kind of commands.
Obviously, they must be commands that run in a terminal, not open their own

You need the following two files from winpty:


You can download them from the following page:


Just put the files somewhere in your PATH.  You can set the 'winptydll' option
to point to the right file, if needed.  If you have both the 32-bit and 64-bit
version, rename to winpty32.dll and winpty64.dll to match the way Vim was

Environment variables are used to pass information to the running job:
    VIM_SERVERNAME      v:servername

2. Remote testing                                       terminal-testing

Most Vim tests execute a script inside Vim.  For some tests this does not
work, running the test interferes with the code being tested.  To avoid this
Vim is executed in a terminal window.  The test sends keystrokes to it and
inspects the resulting screen state.


term_sendkeys()         send keystrokes to a terminal (not subject to tmap)
term_wait()             wait for screen to be updated
term_scrape()           inspect terminal screen

3. Diffing screen dumps                                 terminal-diff

In some cases it can be bothersome to test that Vim displays the right
characters on the screen.  E.g. with syntax highlighting.  To make this
simpler it is possible to take a screen dump of a terminal and compare it to
an expected screen dump.

Vim uses the window size, text, color and other attributes as displayed.  The
Vim screen size, font and other properties do not matter.  Therefore this
mechanism is portable across systems.  A conventional screenshot would reflect
all differences, including font size and family.

Writing a screen dump test for Vim 
For an example see the Test_syntax_c() function in
src/testdir/test_syntax.vim.  The main parts are:
- Write a file you want to test with. This is useful for testing syntax
  highlighting.  You can also start Vim with en empty buffer.
- Run Vim in a terminal with a specific size.  The default is 20 lines of 75
  characters.  This makes sure the dump is always this size.  The function
  RunVimInTerminal() takes care of this.  Pass it the arguments for the Vim
- Send any commands to Vim using term_sendkeys().  For example: 
        call term_sendkeys(buf, ":echo &lines &columns\<CR>")
- Check that the screen is now in the expected state, using
  VerifyScreenDump().  This expects the reference screen dump to be in the
  src/testdir/dumps/ directory.  Pass the name without ".dump".  It is
  recommended to use the name of the test function and a sequence number, so
  that we know what test is using the file.
- Repeat sending commands and checking the state.
- Finally stop Vim by calling StopVimInTerminal().

The first time you do this you won't have a screen dump yet.  Create an empty
file for now, e.g.: 
        touch src/testdir/dumps/Test_function_name_01.dump

The test will then fail, giving you the command to compare the reference dump
and the failed dump, e.g.: 
        call term_dumpdiff("Test_func.dump.failed", "dumps/Test_func.dump")

Use this command in Vim, with the current directory set to src/testdir.
Once you are satisfied with the test, move the failed dump in place of the
        :!mv Test_func.dump.failed dumps/Test_func.dump

Creating a screen dump 

To create the screen dump, run Vim (or any other program) in a terminal and
make it show the desired state.  Then use the term_dumpwrite() function to
create a screen dump file.  For example: 
        :call term_dumpwrite(77, "mysyntax.dump")

Here "77" is the buffer number of the terminal.  Use :ls! to see it.

You can view the screen dump with term_dumpload(): 
        :call term_dumpload("mysyntax.dump")

To verify that Vim still shows exactly the same screen, run Vim again with
exactly the same way to show the desired state.  Then create a screen dump
again, using a different file name: 
        :call term_dumpwrite(88, "test.dump")

To assert that the files are exactly the same use assert_equalfile(): 
        call assert_equalfile("mysyntax.dump", "test.dump")

If there are differences then v:errors will contain the error message.

Comparing screen dumps 

assert_equalfile() does not make it easy to see what is different.
To spot the problem use term_dumpdiff(): 
        call term_dumpdiff("mysyntax.dump", "test.dump")

This will open a window consisting of three parts:
1.  The contents of the first dump
2.  The difference between the first and second dump
3.  The contents of the second dump

You can usually see what differs in the second part.  Use the 'ruler' to
relate it to the position in the first or second dump.

Alternatively, press "s" to swap the first and second dump. Do this several
times so that you can spot the difference in the context of the text.

4. Debugging                                            terminal-debug

The Terminal debugging plugin can be used to debug a program with gdb and view
the source code in a Vim window.  Since this is completely contained inside
Vim this also works remotely over an ssh connection.

Load the plugin with this command: 
        packadd termdebug
To start debugging use :Termdebug followed by the command name, for example: 
        :Termdebug vim

This opens two windows:

gdb window      A terminal window in which "gdb vim" is executed.  Here you
                can directly interact with gdb.  The buffer name is "!gdb".

program window  A terminal window for the executed program.  When "run" is
                used in gdb the program I/O will happen in this window, so
                that it does not interfere with controlling gdb.  The buffer
                name is "gdb program".

The current window is used to show the source code.  When gdb pauses the
source file location will be displayed, if possible.  A sign is used to
highlight the current position, using highlight group debugPC.   

If the buffer in the current window is modified, another window will be opened
to display the current gdb position.

Focus the terminal of the executed program to interact with it.  This works
the same as any command running in a terminal window.

When the debugger ends, typically by typing "quit" in the gdb window, the two
opened windows are closed.

Example session 
Start in the Vim "src" directory and build Vim: 
        % make
Start Vim: 
        % ./vim
Load the termdebug plugin and start debugging Vim: 
        :packadd termdebug
        :Termdebug vim
You should now have three windows:
    source  - where you started, has a window toolbar with buttons
    gdb     - you can type gdb commands here
    program - the executed program will use this window

You can use CTRL-W CTRL-W or the mouse to move focus between windows.
Put focus on the gdb window and type: 
        break ex_help
Vim will start running in the program window. Put focus there and type: 
        :help gui
Gdb will run into the ex_help breakpoint.  The source window now shows the 
ex_cmds.c file.  A ">>" marker will appear where the breakpoint was set.  The
line where the debugger stopped is highlighted.  You can now step through the
program.  Let's use the mouse: click on the "Next" button in the window
toolbar.  You will see the highlighting move as the debugger executes a line
of source code.

Click "Next" a few times until the for loop is highlighted.  Put the cursor on
the end of "eap->arg", then click "Eval" in the toolbar.  You will see this
        "eap->arg": 0x555555e68855 "gui" 
This way you can inspect the value of local variables.  You can also focus the
gdb window and use a "print" command, e.g.: 
        print *eap
If mouse pointer movements are working, Vim will also show a balloon when the
mouse rests on text that can be evaluated by gdb.

Now go back to the source window and put the cursor on the first line after
the for loop, then type: 
You will see a ">>" marker appear, this indicates the new breakpoint.  Now
click "Cont" in the toolbar and the code until the breakpoint will be

You can type more advanced commands in the gdb window.  For example, type: 
        watch curbuf
Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution
will now continue until the value of "curbuf" changes, which is in do_ecmd().
To remove this watchpoint again type in the gdb window: 
        delete 3

You can see the stack by typing in the gdb window: 
Move through the stack frames, e.g. with: 
        frame 3
The source window will show the code, at the point where the call was made to
a deeper level.

Stepping through code 
Put focus on the gdb window to type commands there.  Some common ones are:
- CTRL-C        interrupt the program
- next          execute the current line and stop at the next line
- step          execute the current line and stop at the next statement,
                entering functions
- finish        execute until leaving the current function
- where         show the stack
- frame N       go to the Nth stack frame
- continue      continue execution

In the window showing the source code these commands can be used to control gdb:
 :Run [args]      run the program with [args] or the previous arguments
 :Arguments {args}  set arguments for the next :Run

 :Break       set a breakpoint at the current line; a sign will be displayed
 :Clear       delete the breakpoint at the current line

 :Step        execute the gdb "step" command
 :Over        execute the gdb "next" command (`:Next` is a Vim command)
 :Finish      execute the gdb "finish" command
 :Continue    execute the gdb "continue" command
 :Stop        interrupt the program

If 'mouse' is set the plugin adds a window toolbar with these entries:
  Step          :Step
  Next          :Over
  Finish        :Finish
  Cont          :Continue
  Stop          :Stop
  Eval          :Evaluate
This way you can use the mouse to perform the most common commands.  You need
to have the 'mouse' option set to enable mouse clicks.

You can add the window toolbar in other windows you open with: 

Inspecting variables 
 :Evaluate        evaluate the expression under the cursor
 K                same
 :Evaluate {expr}   evaluate {expr}
 :'<,'>Evaluate     evaluate the Visually selected text

This is similar to using "print" in the gdb window.
You can usually shorten :Evaluate to :Ev.

Other commands 
 :Gdb          jump to the gdb window
 :Program      jump to the window with the running program

There is another, hidden, buffer, which is used for Vim to communicate with
gdb.  The buffer name is "gdb communication".  Do not delete this buffer, it
will break the debugger.


GDB command                                              termdebug-customizing

To change the name of the gdb command, set the "termdebugger" variable before
invoking :Termdebug: 
        let termdebugger = "mygdb"
Only debuggers fully compatible with gdb will work.  Vim uses the GDB/MI
interface.  The "new-ui" command  requires gdb version 7.12 or later.  if you
get this error:
        Undefined command: "new-ui". Try "help".
Then your gdb is too old.

Colors                                          hl-debugPC hl-debugBreakpoint

The color of the signs can be adjusted with these highlight groups:
- debugPC               the current position
- debugBreakpoint       a breakpoint

The defaults are, when 'background' is "light":
  hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
  hi debugBreakpoint term=reverse ctermbg=red guibg=red

When 'background' is "dark":
  hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
  hi debugBreakpoint term=reverse ctermbg=red guibg=red

Popup menu                                              termdebug_popup

By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds
these entries to the popup menu:
        Set breakpoint          :Break
        Clear breakpoint        :Clear
        Evaluate                :Evaluate
If you don't want this then disable it with: 
        let g:termdebug_popup = 0

Vim window width                                                termdebug_wide

To change the width of the Vim window when debugging starts, and use a
vertical split: 
  let g:termdebug_wide = 163
This will set &columns to 163 when :Termdebug is used.  The value is restored
when quitting the debugger.
If g:termdebug_wide is set and &Columns is already  larger than
g:termdebug_wide then a vertical split will be used without changing &columns.
Set it to 1 to get a vertical split without every changing &columns (useful
for when the terminal can't be resized by Vim).


Quick links: help overview · quick reference · user manual toc · reference manual toc · faq