Configuring Vim on Mac OS X

All configuration options for vim are stored in the user’s home directory in a file named .vimrc

The script code is below but there are somethings you’ll want to do before setting it up.

You’ll need to create directories for the following: backups, colors, swaps and undo.

Execute this command to set up the directories in the terminal ( The ~ character will set the path to your home directory. ex: /Users/username/ ):

$ cd ~/.vim ; mkdir backups ; mkdir colors ; mkdir swaps; mkdir undo;

This will keep all your backups, swaps and undos in your .vim user directory. Also the colors directory is for installing themes.

Visit if you would like to download a color scheme. Once you find a color scheme you like, just download it and copy and paste the code into the relevant scheme file and place the file in ~/.vim/colors/

For example if you download the Candy theme, you would name the file candy.vim and place it in the relevant directory described above. Then in your .vimrc config file you would set the theme like so:

" Set color scheme
colorscheme candy

I've created a github repo with the .vimrc configuration. Please take a look at the repo and download from here.

Checkout or download the git zip and setup the .vimrc file by using the cp command.

$ cd ~/Downloads/MacOSVimConfig-master
$ cp vimrc-example ~/.vimrc

Otherwise you can create your .vimrc file by copying the Raw text from github and pasting the text below. NOTE: While in vim before you paste try doing this command.

:set paste

This should paste the text with the best result. Once the .vimrc file is configured open a new terminal windows and open a file to test out the setup.

$ vim ~/.vimrc

------------ .vimrc example configuration ------------------

Then paste in these configuration options:

" Make Vim more useful
set nocompatible
" Use the OS clipboard by default (on versions compiled with `+clipboard`)
" Set color scheme!¬
colorscheme candy
set clipboard=unnamed
" Enhance command-line completion
set wildmenu
" Allow cursor keys in insert mode
set esckeys
" Allow backspace in insert mode
set backspace=indent,eol,start
" Optimize for fast terminal connections
set ttyfast
" Add the g flag to search/replace by default
set gdefault
" Use UTF-8 without BOM
set encoding=utf-8 nobomb
" Change mapleader
let mapleader=","
" Don’t add empty newlines at the end of files
set binary
set noeol
" Centralize backups, swapfiles and undo history
set backupdir=~/.vim/backups
set directory=~/.vim/swaps
if exists("&undodir")
	set undodir=~/.vim/undo

set viminfo+=! " make sure vim history works
map <C-J> <C-W>j<C-W>_ " open and maximize the split below
map <C-K> <C-W>k<C-W>_ " open and maximize the split above
set wmh=0 " reduces splits to a single line 

" Enable per-directory .vimrc files and disable unsafe commands in them
set exrc
set secure
" Enable syntax highlighting
syntax on
" Highlight current line
set cursorline
" Make tabs as wide as two spaces
set tabstop=2
" Enable line numbers
set number
" Show “invisible” characters
set lcs=tab:▸\ ,trail:·,eol:¬,nbsp:_
set list
" Highlight searches
set hlsearch
" Ignore case of searches
set ignorecase
" Highlight dynamically as pattern is typed
set incsearch
" Always show status line
set laststatus=2
" Respect modeline in files
set modeline
set modelines=4
" Enable mouse in all modes
set mouse=a
" Disable error bells
set noerrorbells
" Don’t reset cursor to start of line when moving around.
set nostartofline
" Show the cursor position
set ruler
" Don’t show the intro message when starting Vim
set shortmess=atI
" Show the current mode
set showmode
" Show the filename in the window titlebar
set title
" Show the (partial) command as it’s being typed
set showcmd

" Start scrolling three lines before the horizontal window border
set scrolloff=3

" Strip trailing whitespace (,ss)
function! StripWhitespace()
	let save_cursor = getpos(".")
	let old_query = getreg('/')
	call setpos('.', save_cursor)
	call setreg('/', old_query)
noremap <leader>ss :call StripWhitespace()<CR>
" Save a file as root (,W)
noremap <leader>W :w !sudo tee % > /dev/null<CR>

" Automatic commands
if has("autocmd")
	" Enable file type detection
	filetype on
	" Treat .json files as .js
	autocmd BufNewFile,BufRead *.json setfiletype json syntax=javascript

15 Responses so far.

  1. Paul says:


    This stuff is generally awesome, but needs a little clarification. Or at least these are some variations I had to make to get things working.

    “colorscheme candy·¬” should be “colorscheme candy¬”
    Otherwise vim throws an error saying it can’t find the color theme “candy·”

    While you do say “copy and paste”, it’s very easy for people to just download candy.vim into ~/.vim/colors and if you do, the file has a bunch of “^M”s which break the color theme loading.

    The two mapping commands on lines 33 & 34 are generating “No mapping found commands”. It’s not clear to me what is suppose to be mapped there. Generally map takes two arguments and “j_” and “k_” appear to be single arguments.

    The “candy” color theme doesn’t produce a black background. To get it working I had to add the following line to the end of ~.vimrc:

    “hi Normal ctermbg=black ctermfg=white¬”

    I hope you found all this helpful.



  2. Tim says:

    I’ve created a .vimrc file that can now be downloaded. Also I’ve cleaned up the text and fixed the issues surrounding the j and k key bindings and the colorscheme setting, for those that might want to still copy and paste. However as Paul suggests you are better off trying the download option first. Thanks Paul!

  3. Kianoesh Shademan says:

    Hey Tim,

    First of all, thanks for this guide, it helped me get some beginner understanding of the .vimrc file.

    Im getting the following errors while opening vi files, it seems that it can’t process the candy.vim color scheme :( I rlly want it!

    Does this say anything to you?

    Error detected while processing /home/kianoesh/.vim/colors/candy.vim:
    line 6:
    E492: Not an editor command: ^M
    line 7:
    E474: Invalid argument: background=dark^M
    line 8:
    E411: highlight group not found: clear^M
    line 9:
    E15: Invalid expression: exists(“syntax_on”)^M
    line 79:
    E171: Missing :endif

    Thanks in advance!

    Kianoesh Shademan

    • Tim says:

      Hi Kianoesh! Thanks for replying. I’ve been busy working on an iOS app but I have some time to help you with the file. It looks like carriage returns and maybe some other chars are creating issues. I will email you directly and we can meet up on chat if you want.

      • Jason says:

        Hi Tim! Thanks for the great tutorial, I have the exact same problem as Kianoesh. How did you guys fix this?

        • Tim says:

          What exactly is breaking for you? Which unwanted characters are visible? You can download the custom-vimrc.text and open it in vim and remove any unwanted characters from it. Let me know what you find. Thanks!

  4. Johnd611 says:

    Excellent blog here! Also your web site loads up very fast! What web host are you using? Can I get your affiliate link to your host? I wish my website loaded up as quickly as yours lol bcdfdeedeged

  5. David says:

    Hi Tim,

    Thanks a lot for the article. However, when I open any file with vim, it gives me the following errors for every line of candy.vim. But it seems that the error does not effect my use. I’m new using vim, could you please help me figure this out?

    Error detected while processing /Users/amadeus/.vim/colors/candy.vim:
    line 1:
    E477: No ! allowed:
    line 2:
    E488: Trailing characters:
    line 4:
    E488: Trailing characters:
    line 5:
    E488: Trailing characters: <link rel=
    line 6:
    E488: Trailing characters: candy.vim – color scheme ( background is black ) : vim online

  6. Vaibhav says:

    Useful stuff guys.
    Don’t need copy paste in full, I chose my stuff.


  7. Kevin says:

    Very helpful. Thanks. I’m getting the Control-M issue though that is being caused by the .vimrc file. Not sure where it is. But when I cp custom-vimrc-file.txt to ~/.vimrc everything I try to open in vi has control-M’s in it. Going through the file right now to try and isolate the culprit, but didn’t know if anyone else already found it and has a quick fix.

  8. […] on Mac OS X. The .vimrc example file is now hosted on github.  Check out the article here.  Users were having issues copying and pasting the config file, so I recommend trying to download […]

Leave a Reply