sponsor Vim development Vim logo Vim Book Ad

asyncrun : Run Async Shell Commands in Vim 8.0 and Output to Quickfix in Realtime

 script karma  Rating 1772/527, Downloaded by 13409  Comments, bugs, improvements  Vim wiki

created by
Wei Lin
script type
Maintainer: skywind3000 (at) gmail.com
Homepage: https://github.com/skywind3000/asyncrun.vim

Run shell commands in background and output to quickfix:
    :AsyncRun[!] [options] {cmd} ...

    when "!" is included, auto-scroll in quickfix will be disabled
    parameters are splited by space, if a parameter contains space,
    it should be escaped as backslash + space (just like ex commands)

Parameters will be expanded if they start with '%', '#' or '<' :
    %:p     - File name of current buffer with full path
    %:t     - File name of current buffer without path
    %:p:h   - File path of current buffer without file name
    %:e     - File extension of current buffer
    %:t:r   - File name of current buffer without path and extension
    %       - File name relativize to current directory
    %:h:.   - File path relativize to current directory
    <cwd>   - Current directory
    <cword> - Current word under cursor
    <cfile> - Current file name under cursor
    <root>  - Project root directory

Environment variables are set before executing:
    $VIM_FILEPATH  - File name of current buffer with full path
    $VIM_FILENAME  - File name of current buffer without path
    $VIM_FILEDIR   - Full path of current buffer without the file name
    $VIM_FILEEXT   - File extension of current buffer
    $VIM_FILENOEXT - File name of current buffer without path and extension
    $VIM_CWD       - Current directory
    $VIM_RELDIR    - File path relativize to current directory
    $VIM_RELNAME   - File name relativize to current directory
    $VIM_ROOT      - Project root directory
    $VIM_CWORD     - Current word under cursor
    $VIM_CFILE     - Current filename under cursor
    $VIM_GUI       - Is running under gui ?
    $VIM_VERSION   - Value of v:version
    $VIM_COLUMNS   - How many columns in vim's screen
    $VIM_LINES     - How many lines in vim's screen

    parameters also accept these environment variables wrapped by
    "$(...)", and "$(VIM_FILEDIR)" will be expanded as file directory

    Macro $(VIM_ROOT) and <root> (new in version 1.3.12) indicate the
    Project Root of the current file.

There can be some options before [cmd]:
    -mode=0/1/2  - start mode: 0(async,default), 1(makeprg), 2(!)
    -cwd=?       - initial directory, (use current directory if unset)
    -save=0/1    - non-zero to save unsaved files before executing
    -program=?   - set to 'make' to use '&makeprg'
    -post=?   - vimscript to exec after this job finished, spaces **must** be escaped to '\ '
    -raw=1    - don't matching the errorformat, output directly in the quickfix window.

    All options must start with a minus and position **before** `[cmd]`.
    Since no shell command starts with a minus. So they can be
    distinguished from shell command easily without any ambiguity.

Stop the running job by signal TERM:

    when "!" is included, job will be stopped by signal KILL

    g:asyncrun_exit - script will be executed after finished
    g:asyncrun_bell - non-zero to ring a bell after finished (notify you job finished)
    g:asyncrun_mode - 0:async(if support) 1:sync 2:shell
    g:asyncrun_encs - shell program output encoding

    g:asyncrun_code - exit code
    g:asyncrun_status - 'running', 'success' or 'failure'

    minimal vim version is 7.4.1829 to support async jobs.
    neovim 0.1.4 or later is supported too.
    recommand to use vim 8.0 or above.

    AsyncRun uses quickfix window to show job outputs, in order to see the outputs in realtime,
    you need open quickfix window at first by using :copen (see :help copen). And there is a
    function 'asyncrun#quickfix_toggle(size)' for you to open/close it rapidly (see tutorial 9).

Tutorial 0: async run gcc / make to build current file
    :AsyncRun gcc % -o %<
    :AsyncRun g++ -O3 "%" -o "%<" -lpthread
    :AsyncRun make -f Mymakefile

Tutorial 1: async grep key word
    :AsyncRun! grep -R word .
    :AsyncRun! grep -R <cword> .

Tutorial 2: look up man page
    :AsyncRun! man -S 3:2:1 <cword>

Tutorial 3: build go project
    :AsyncRun go build "%:p:h"

Tutorial 4: use <F7> to compile current file
    :noremap <F7> :AsyncRun gcc "%" -o "%<" <cr>

Tutorial 5: open quickfix window (see the output)
    :botright copen 8

Tutorial 6: async git push
    :AsyncRun git push origin master

Tutorial 7: compile markdown to pdf
    :AsyncRun pandoc --output "$(VIM_FILENOEXT).pdf" "%:p" <CR>

Tutorial 8: update tags in background while editing (super useful for large projects):
    :AsyncRun ctags -R --fields=+S .
    :AsyncRun ctags -R -f $(VIM_FILEDIR)/ctags.out --fields=+iaS $(VIM_FILEDIR)

Tutorial 9: a help function to toggle quickfix window in an efficient way (F9 to toggle):
    :noremap <F9> :call asyncrun#quickfix_toggle(8)<cr>

Please vote it if you like it.
install details
Copy asyncrun.vim to your ~/.vim/plugin or use Vundle to install it from skywind3000/asyncrun.vim .

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
asyncrun.vim 2.12.9 2024-05-22 8.0 Wei Lin - fixed shellslash issue on Windows.
asyncrun.vim 2.12.8 2024-05-21 8.0 Wei Lin Force to use "cmd.exe" as "g:asyncrun_shell" on Windows.
asyncrun.vim 2.12.6 2024-05-13 8.0 Wei Lin Update script_write() to write files silently to avoid displaying unnecessary messages.
asyncrun.vim 2.12.5 2024-03-22 8.0 Wei Lin - set `g:asyncrun_mode` to 1 during creating a terminal buffer and clear it to 0 after buffer has been created.
- script triggered by the `#TerminalOpen` or `#TermOpen` autocmd can use it to detect if this terminal is created by asyncrun.
asyncrun.vim 2.12.4 2024-02-20 8.0 Wei Lin Refactor root locator function and update AsyncRun plugin version to 2.12.4
asyncrun.vim 2.12.3 2024-02-16 8.0 Wei Lin - Added handling for fugitive buffers in "asyncrun#fullname()" function
asyncrun.vim 2.12.2 2023-09-30 8.0 Wei Lin - accept "AsyncRun :!!command" to start GUI programs.
- minor issues fixed.
asyncrun.vim 2.11.23 2023-09-20 8.0 Wei Lin - added try/catch for Ex commands (starting with colon), eg. ":AsyncRun  :echo 123" and display exception if failed.
- fixed minor issues.
asyncrun.vim 2.11.20 2023-08-21 8.0 Wei Lin new api "asyncrun#current_root()" can return the current root directory.
asyncrun.vim 2.11.19 2023-08-03 8.0 Wei Lin - new "-init=script" option to run a init script for terminal task after successfully opening the terminal window.
- new "-ft=filetype" option to set filetype for a terminal buffer.
asyncrun.vim 2.11.16 2023-03-02 8.0 Wei Lin Strip message even if process fails
asyncrun.vim 2.11.15 2023-01-18 8.0 Wei Lin - new option "-runner=xxx" can work as an alias to "-mode=term -pos=xxx".
- polish external function calling
asyncrun.vim 2.11.14 2022-11-29 8.0 Wei Lin - terminal: only reuse terminal window created by asyncrun, prevent side-effect to other terminal plugins;
- terminal: simplify terminal reusable check routine;
- terminal: enable reuse by default for split terminal (can be disabled by -reuse=0);
- terminal: enable autoscroll for terminal buffers in a non-active window (-focus=0);
- terminal: accept "-scroll=0" to keep consistency with quickfix window.
asyncrun.vim 2.11.9 2022-11-28 8.0 Wei Lin vim-7.4.1829 compliance
asyncrun.vim 2.11.6 2022-11-21 8.0 Wei Lin - terminal: initialize a proper terminal name for vim-8.2 and above.
- terminal: enable safe-argument-passing mode for vim-8.2 and above.
- terminal: wipe previous finished terminal buffer when '-reuse' is presented.
- remove unnecessary messages.
asyncrun.vim 2.11.3 2022-11-19 8.0 Wei Lin - new option g:asyncrun_term_wipe, set to non-zero to change the &bufhidden of terminal buffer to 'wipe' when command finished.
- the default value of g:asyncrun_term_wipe is 1.
asyncrun.vim 2.10.9 2022-11-03 8.0 Wei Lin - revert command completion mode from "shellcmd" back to "file" because
- The '%' will not be substituted when using "shellcmd", see: #264
asyncrun.vim 2.10.8 2022-11-02 8.0 Wei Lin - improve nomodeline compatibility
- take care of the "&makeencoding" option;
- provide more information for runners and translators.
asyncrun.vim 2.10.6 2022-10-30 8.0 Wei Lin - fix: Use shellcmd completion for AsyncRun, see: #261
- new runner for toggleterm: #257
asyncrun.vim 2.10.5 2022-10-12 8.0 Wei Lin - Use <nomodeline> in :doautocmd, see #259.
- new option g:asyncrun_show_time, set to 1 to display the command start time in the first line of quickfix window.
asyncrun.vim 2.10.0 2022-10-06 8.0 Wei Lin - new :AsyncReset command to reset all internal status.
- fix: tab page restoration when "focus=0" & "reuse=1"
- supports quickfix-id
- keep compatible with vim-7.4.1829
- better project root detection.
asyncrun.vim 2.9.9 2022-02-03 8.0 Wei Lin - new option g:asyncrun_pathfix to correct relative path mismatching issue in the quickfix window.
- better arguments extracting.
asyncrun.vim 2.9.7 2021-12-24 8.0 Wei Lin - new option "-encoding=?" makes it possible to specify encoding for each command's stdout independently.
- fixed: "-focus=0" can't return previous tabpage with "-pos=TAB"
asyncrun.vim 2.9.5 2021-12-20 8.0 Wei Lin - new `-once` option to buffer all output and flush them at once when job is finished (behave like vim-dispatch)
- fix: when the terminal is the last window `-mode=term -close=1` will exit vim.
asyncrun.vim 2.9.3 2021-12-18 8.0 Wei Lin - externalize "-program=xxx" script to autoload/asyncrun/program
- new option "-scroll=0" to disable quickfix auto-scrolling
asyncrun.vim 2.9.1 2021-12-16 8.0 Wei Lin - unified terminal closing behavior in both vim & neovim when -mode=term & -close=1
asyncrun.vim 2.8.9 2021-12-15 8.0 Wei Lin - fire AsyncRunInit autocmd when first calling :AsyncRun command.
- new event dispatch mechanism.
- better runner handling.
asyncrun.vim 2.8.5 2021-03-28 8.0 Wei Lin better terminal cwd handling.
asyncrun.vim 2.8.2 2021-02-03 8.0 Wei Lin new option -pos=TAB for -mode=term to open a terminal in a new tab residing on the left side.
new option -close for -mode=term to close the terminal automatically when terminal process finished.
asyncrun.vim 2.8.1 2021-02-03 8.0 Wei Lin fixed: minor path related issues.
improve compatibility on windows.

asyncrun.vim 2.7.9 2021-01-29 8.0 Wei Lin new: when -mode=wait is provided, use system() to run your command.
asyncrun.vim 2.7.8 2021-01-12 8.0 Wei Lin expose s:ScriptWrite interface to asyncrun#script_write.
asyncrun.vim 2.7.7 2020-12-29 8.0 Wei Lin add autocmd AsyncRunInterrupt when job is stopped by AsyncStop
asyncrun.vim 2.7.5 2020-04-09 8.0 Wei Lin Project root can be overshadowed by b:asyncrun_root, t:asyncrun_root and g:asyncrun_root.
asyncrun.vim 2.7.3 2020-04-08 8.0 Wei Lin New macro $(VIM_PWD) to store vim's working directory (:pwd returns), different from $(VIM_CWD) which will follow "-cwd=xxx" option.
asyncrun.vim 2.7.1 2020-03-26 8.0 Wei Lin keep compatible to vim 7.3 with limited functionality.
asyncrun.vim 2.7.0 2020-03-25 8.0 Wei Lin windows: follow "shellslash" option
asyncrun.vim 2.6.9 2020-03-23 8.0 Wei Lin improve project root detection
asyncrun.vim 2.6.8 2020-03-22 8.0 Wei Lin change: g:asyncrun_rootmarks accepts wildcards like "*" or "?".
change: -reuse=0 can be used in split terminals.

asyncrun.vim 2.6.7 2020-03-12 8.0 Wei Lin fixed: windows - exit code is always zero.
asyncrun.vim 2.6.6 2020-03-11 8.0 Wei Lin new: -pos accepts a new uppercase TAB to open internal terminal on the left of current tab.
asyncrun.vim 2.6.2 2020-03-08 8.0 Wei Lin runner function's argument has been changed from string to a dictionary for flexibility.
asyncrun.vim 2.6.0 2020-03-07 8.0 Wei Lin 1. change: -post=xxx is available in terminal mode
2. new: -pos=hide in terminal mode
3. new: -name=abc to specify a name for terminal task
4. new: g:asyncrun_name to get terminal task name.
asyncrun.vim 2.5.5 2020-03-07 8.0 Wei Lin change: "-mode=term -pos=tab" now obeys "-focus=0".
asyncrun.vim 2.5.4 2020-03-06 8.0 Wei Lin fixed minor issues, windows: correctly passing arguments
asyncrun.vim 2.5.3 2020-03-02 8.0 Wei Lin 1. new option -silent to prevent open quickfix window no matter g:asyncrun_open is set or not.
2. new command modifier can define your own "-program=new_modifer".

asyncrun.vim 2.5.0 2020-02-29 8.0 Wei Lin 1. purify and refactor, remove useless codes.
2. new command modifier g:asyncrun_program.
3. the "-program=xx" supports msys, mingw32, mingw64 and cygwin.
asyncrun.vim 2.4.9 2020-02-21 8.0 Wei Lin new: specify customized runner by g:asyncrun_runner, see customize runners.
new: run command with :execute if command is starting with a colon :.
new: the colon command can be disabled by setting g:asyncrun_strict to non-zero.

asyncrun.vim 2.4.6 2020-02-18 8.0 Wei Lin new macros for -program=wsl on Windows:
asyncrun.vim 2.4.5 2020-02-17 8.0 Wei Lin - "$(VIM_PATHNOEXT)" is not an absolute path, make it absolute.
asyncrun.vim 2.4.4 2020-02-16 8.0 Wei Lin 1. Fixed:neovim "-mode=term -safe=1" will break when home directory contains spaces
2. Optimize in terminal mode.
asyncrun.vim 2.4.3 2020-02-16 8.0 Wei Lin 1. fixed: neovim+windows: arguments containing spaces break on windows.
asyncrun.vim 2.4.2 2020-02-16 8.0 Wei Lin Add new macro $(VIM_FILETYPE)
asyncrun.vim 2.4.1 2020-02-12 7.0 Wei Lin fixed: focusing issue in an internal terminal window.
asyncrun.vim 2.2.9 2020-02-10 8.0 Wei Lin new terminal mode options: `-safe=1`, `-listed=0` and `-reuse`
asyncrun.vim 2.2.6 2020-02-06 8.0 Wei Lin new: parameter `-hidden` when using `-mode=term` to set `bufhidden` to `hidden`
improve: keep alternative window when splitting an terminal window
improve: more safe to start a terminal in a new tab
asyncrun.vim 2.2.3 2020-02-05 8.0 Wei Lin new: "-program=wsl" to run command in wsl (windows 10 only).
asyncrun.vim 2.2.2 2020-02-05 8.0 Wei Lin new option "-pos=curwin" to open terminal in current window.
asyncrun.vim 2.2.1 2020-01-20 8.0 Wei Lin set noreletivenumber for terminal window.
asyncrun.vim 2.2.0 2020-01-18 8.0 Wei Lin new `-focus=0` option for `-mode=term` to prevent focus change.
asyncrun.vim 2.1.9 2020-01-12 8.0 Wei Lin polish `-mode=term`, omit `number` and `signcolunm` in terminal
asyncrun.vim 2.1.7 2020-01-11 8.0 Wei Lin new options `errorformat` in asyncrun#run(...)
asyncrun.vim 2.1.1 2020-01-09 8.0 Wei Lin new: "AsyncRun -mode=term -pos=bottom -rows=10 xxx" to run command in a resuable terminal window.
asyncrun.vim 2.0.8 2019-04-28 7.4 Wei Lin Handle tcd which was introduced in vim 8.1.1218.
asyncrun.vim 2.0.7 2019-01-28 8.0 Wei Lin restore g:asyncrun_stdin because rg will break on windows if stdin is not null.
asyncrun.vim 2.0.6 2019-01-26 8.0 Wei Lin More adaptive to handle stdin and remove g:asyncrun_stdin option.
asyncrun.vim 2.0.5 2019-01-13 8.0 Wei Lin enable stdin on windows by default to fix cmake stdin warnings on windows.
asyncrun.vim 2.0.4 2019-01-13 7.4 Wei Lin new option `g:asyncrun_stdin`, set to 1 to enable stdin (fix cmake warnings on windows).
asyncrun.vim 2.0.3 2019-01-04 7.4 Wei Lin new environment variable: $VIM_PATHNOEXT - Current file name with full path but without extension
new environment variable: $VIM_HOME - first runtime path
asyncrun.vim 2.0.1 2018-04-28 7.4 Wei Lin New option g:asyncrun_save to save files before executing.
asyncrun.vim 2.0.0 2018-04-27 7.4 Wei Lin Improve neovim compatibility and handle `tcd` command correctly.
asyncrun.vim 1.3.27 2018-04-18 7.4 Wei Lin new: can take a range of text in current buffer as job's stdin.
asyncrun.vim 1.3.26 2018-04-16 7.4 Wei Lin new option `g:asyncrun_wrapper` to enable setup a command prefix.
asyncrun.vim 1.3.25 2018-04-16 7.4 Wei Lin handle makeprg/grepprg correctly, accept `%` and `$*` macros.
asyncrun.vim 1.3.22 2018-03-12 7.4 Wei Lin new option "g:asyncrun_open" to open quickfix automatically.
asyncrun.vim 1.3.19 2017-12-13 7.4 Wei Lin new option asyncrun_skip to disable specific autocmds
asyncrun.vim 1.3.17 2017-08-06 7.4 Wei Lin fixed: process will hang when mode is 5
fixed: g:asyncrun_mode issue.
fixed: remove trailing new line in neovim, improve asyncrun#execute.
improve asyncrun#get_root(), allow user to specify the rootmarkers
new option "-raw" to prevent output matching the errorformat, useful when you are running a script.
Refactor, support <root> macro to indicate project root (depends on root markers)
asyncrun.vim 1.3.11 2017-05-19 7.4 Wei Lin New option (-save=2) to save all modified buffers before executing.
asyncrun.vim 1.3.8 2016-11-17 7.4 Wei Lin 1. fixed conflict between caddexpr and command line window.
2. add autocmd AsyncRunPre, AsyncRunStart and AsyncRunStop.
asyncrun.vim 1.3.7 2016-11-13 7.4 Wei Lin 1. fixed issues in channel reading and arguments parsing
2. flow control to prevent gui freeze by massive output
asyncrun.vim 1.3.6 2016-11-07 7.4 Wei Lin improve performance by add some noautocmd, fixed small issue in bell ringing. improve event hooking
asyncrun.vim 1.3.5 2016-11-02 7.4 Wei Lin new option "g:asyncrun_auto" and "-auto=?" to trigger QuickFixCmdPre and QuickFixCmdPost. and can cooperate with errormaker.vim now
asyncrun.vim 1.3.3 2016-10-27 7.4 Wei Lin 1. new option "g:asyncrun_local" to use local value of errorformat rather the global value.
2. prevent job who reads from stdin getting hanging by setting in_io to null.
3. fixed an issue in fast exiting programs
asyncrun.vim 1.3.2 2016-10-19 7.4 Wei Lin 1. fixed few issues of arguments passing in different modes
2. new "-post" option to run a vimscript after the job finished
asyncrun.vim 0.0.0 2016-08-24 7.4 Wei Lin Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
Vim at Github