Learn Vim at your own pace with my self-study Core Vim Course.

Learn more

Learn Vim at your own pace with my self-study Core Vim Course.

Using Vim's paste mode with the system paste command


Run time:

When Vim is compiled without the +clipboard feature, we can still insert text from the clipboard using the system paste command (ctrl-v or cmd-v). This can produce strange effects, but we can avoid them by toggling the paste option each time we use the system paste command.


If you copy this snippet of JavaScript, then use the system paste command (ctrl-v, or cmd-v for mac users) to paste it into a Vim session running in the terminal, you might end up with something that looks like this:

for (var i = 1; i <= 100; i++) {
      if (i % 15 == 0) {
                } else if (i % 3 == 0) {
                          } else if (i % 5 == 0) {
                                    } else {

The problem is that when Vim runs inside a terminal, it can’t distinguish between characters that are typed manually and those that are pasted. In this case, each time Vim creates a new line, it’s autoindented. Add on top of that the indentation that was already present the source code, and we end up with each line drifting farther and farther to the right.

We can avoid this by enabling the paste option, which temporarily disables several settings that can interfere when pasting text.

:set paste

With that option enabled, the system paste command should work in Insert mode just fine.

Why not keep ‘paste’ enabled at all times?

You might be thinking: Why not keep the paste option enabled at all times? Here’s the gotcha: when the paste option is enabled, any abbreviations or mappings defined for Insert mode will be disabled. For example, suppose that you have this mapping set up, to swich from Insert to Normal mode by typing kj:

:inoremap kj <Esc>

If the paste option is enabled, then typing kj will insert those characters into the document. But with the paste option disabled, typing kj will behave just as though you pressed <Esc>.

So remember: with the paste option enabled, you’re safe to use the system paste command, but any user-defined Insert mode mappings will fail. For that reason, it’s a good idea to turn off the paste option as soon as you’re finished using it.

If you’re thinking of creating a mapping to make it easier to toggle the paste option, don’t forget that your mapping won’t work in Insert mode! Read Vim’s documentation on 'pastetoggle' to learn about a workaround.

The unimpaired workflow

I like the approach that’s enabled by Tim Pope’s unimpaired plugin. In the documentation, he notes that:

you toggle twice, but you only paste once (YOPO).

Unimpaired provides a yo mapping. Just like the regular o command, it opens a new line and switches to Insert mode, but the yo variant also enables the paste option making it safe to use the system paste command. It uses an autocommand to disable the paste option when you return to Normal mode. That’s a much neater workflow than having to toggle the paste option on and off again manually.

Further reading


Level-up your Vim


Boost your productivity with a Vim training class. Join a public class, or book a private session for your team.

Drew hosted a private Vim session for the shopify team that was one of the best workshops I have ever attended.

John Duff, Director of Engineering at Shopify


Make yourself a faster and more efficient developer with the help of these publications, including Practical Vim (Pragmatic Bookshelf 2012), which has over 50 five-star reviews on Amazon.

After reading it, I've switched to vim as my default editor on a daily basis with no regrets. ★★★★★

Javier Collado

Learn to use Vim efficiently in your Ruby projects

In association with thoughtbot, one of the most well respected Rails consultancies in the world, I've produced a series of screencasts on how to make navigating your Ruby projects with Vim ultra-efficient. Along the way, you’ll also learn how to make Ruby blocks a first-class text object in Vim. This lets you edit Ruby code at a higher level of abstraction. Available to buy from thoughtbot..