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 jupyter-vim Vim plugin adds the ability to connect Vim to the Jupyter kernel started by QtConsole. The situation is thus that there is one Jupyter kernel with two connected clients. Both clients have full access to the state of the kernel, can send commands 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 version 4.4 or newer. You also need the jupyter-vim plugin. The “official” GitHub repository for that plugin is no longer maintained. I recommend grabbing either Bernard Roeler’s branch at: https://github.com/broesler/jupyter-vim or my own: https://github.com/wmvanvliet/jupyter-vim.

For the jupyter-vim 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_client 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/python3.6/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

To make QtConsole output whatever text you send it, 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.

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:

:JupyterConnect

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:

<localleader>R    Run the file
<localleader>I    Import the file
<localleader>d    Change the working directory of the Jupyter kernel
                  to the directory containing this file
<localleader>X    Execute this code cell (delimit with ##, #%% or # )
<localleader>E    Execute this line
<localleader>e    Use with any text-object to execute it. Or in visual 
                  mode: execute selected code

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