Integrating Vim and jupyter-qtconsole

Generally, for those looking for a comfortable Python data analysis environment, I recommend using the Spyder IDE. It aims to mimic MATLAB’s excellent GUI and does a pretty good job of it.

However, I personally shy away from IDE’s and use Vim as my text editor for basically everything. This tip is for those few that are like me that need a comfortable data analysis environment centered around Vim. This can be achieved by coupling Vim to Jupyter’s QtConsole.

The idea is to have an interactive console open for quick commands (“plot this data”, “what is the mean of this thing?”, etc.) and a Vim instance where you work on analysis scripts and so forth.

When you start QtConsole, two processes are created: a Jupyter kernel running IPython and a Jupyter client that connects to the kernel and builds a GUI to interact with it. The vim-ipython Vim plugin adds the ability to connect Vim to the Jupyter kernel started by QtConsole. The situation is thus that there is one IPython kernel with two connected clients. Both clients have full access to the state of the kernel, send command to it, receive results back and can monitor traffic between other clients and the kernel. This setup allows us to make Vim and the QtConsole cooperate nicely.

Installation

Of course, you need to have a python installation with the jupyter-qtconsole package installed. You need the development version: https://github.com/jupyter/qtconsole. Uninstall any previous version you may already have on your machine and install from the Git repository.

You also need the vim-ipython plugin. The “official” GitHub repository for that plugin is no longer maintained. I recommend grabbing either Wilywampa’s branch at: https://github.com/wilywampa/vim-ipython or my own: https://github.com/wmvanvliet/vim-ipython.

For the vim-ipython plugin to work properly, Vim needs to have been compiled with Python support (which it usually is these days) and whatever Python Vim is linked against (usually the system Python) needs to have the jupyter package installed. To find our which Python Vim is using, open Vim and use the command:

:python import sys; print(sys.path)

In my case, Vim tells me /usr/lib/python2.7/site-packages is the first item in its Python path, so my Vim is using the system python located at /usr/bin/python. If this is also the case for you, use your system’s package manager to install Jupyter. If this is not the case for you, or if there is no such official package, use PIP to install it. However, make sure to the PIP binary that is part of the Python installation that Vim is using! (In my case that would be /usr/bin/pip).

Configuration

With a cutting-edge development version of QtConsole, you can set the following in your ~/.jupyter/jupyter_qtconsole_config.py:

c.ConsoleWidget.include_other_output = True

This instructs QtConsole to echo the communication between the IPython kernel and the Vim. This causes the commands send by Vim to the kernel and the response of the kernel to be shown in the QtConsole window. In your vimrc you can then disable the hacky way vim-ipython tries to show you the results of its communication with the kernel:

let g:ipy_monitor_subchannel = 0

Usage

If everything is setup correctly, you should be able to open a QtConsole and a Vim instance running side by side. Then, in Vim, open a Python file and give the following command:

:IPython

Vim will attempt to connect to the IPython kernel. If this is successful you can use (among others) the following keybindings to send Python code to be executed on the kernel:

F5         Run the entire file
F9         Run the selected lines
<leader>d  Get documentation for the function under the cursor

You will see the communication between Vim and the kernel displayed in the QtConsole, prefixed with [remote].