[Vim Series 2] Install and Run Vim for the First Time

In this lesson we will install Vim via Homebrew and create our very first file. macOS ships with Vim, but this series uses the Homebrew build because it is easier to update and reinstall.

What You Will Do

• Install Vim with Homebrew
• Confirm the installation
• Open a file in Vim and enter text
• Save your work and exit

Before You Start

You’ll need:

• Homebrew installed (brew --version should work)
• iTerm2
• A keyboard

Time required: 10–15 minutes

If brew is not installed yet, install Homebrew first and then come back to this post.

How Today’s Vim Session Works

Before you type anything, keep these three states in mind:

• Normal mode: keys act as Vim commands
• Insert mode: keys become text you are typing into the file
• Command-line prompt: after pressing :, you can enter commands such as :wq

Step 1: Install and Verify Vim

Install with Homebrew

Follow the terminal session below to install Vim and check its version.

Seeing the version output means Vim is installed and ready.

Launch iTerm2

⌘ + Space → type "iterm" → press Enter

Step 2: Create a Practice File

Go to the home directory

cd ~
pwd

Expected output:

/Users/your-username

Open a new file in Vim

Run vim practice.txt to start Vim. You should see a screen like the one below.

What the screen tells you:

• ~ marks empty lines
• "practice.txt" [New File] shows the file name and state
• The status area at the bottom shows cursor and file status information
• Exact numbers and labels can vary a little by Vim version and settings

Step 3: Experience Your First Input Failure

Try typing anyway

Action: Press H, e, l, l, o in order.

Expected result: Nothing happens!

Why?

Vim starts in Normal mode.

• In Normal mode every key is treated as a command
• h, j, k, l move your cursor
• You must switch to Insert mode to type text

Step 4: Switch to Insert Mode

Press the i key

Action: Hit i once.

What changed: You now see -- INSERT -- at the bottom.

Start typing text

Action: Enter the following lines:

Hello Vim!
This is my first file.

Step 5: Return to Normal Mode

Press Esc

Action: Hit the Esc key once.

Result: The -- INSERT -- banner disappears, so you are back in Normal mode.

Step 6: Save and Quit

Open the command-line prompt

Action: Press the : key.

What changes:

• From Normal mode, Vim opens its command-line prompt
• The cursor jumps to the bottom
• A colon appears, waiting for a command such as wq, w, or q!

Type the save-and-quit command

Action: Type :wq and press Enter.

Completion message:

[Back in the terminal]

Step 7: Verify the File

Show the saved contents

Use cat to check the file.

🎉 Success! Your first Vim file is safely stored.

Quick Recap

Today’s core flow is:

vim practice.txt -> i -> type text -> Esc -> :wq -> Enter

Command recap:

Common Mistakes

Mistake 1: Quit without saving

Scenario: You made a bad change and want to exit without saving.

Fix:

ESC → :q! → Enter

q means quit; ! forces it even with unsaved changes.

Mistake 2: Save but stay in Vim

Fix:

ESC → :w → Enter

w stands for write—your file is saved but Vim stays open.

Mistake 3: Read-only warning

Error:

E45: 'readonly' option is set (add ! to override)

Fix:

ESC → :w! → Enter

or

ESC → :wq! → Enter

These commands override Vim's own read-only state, but they still cannot bypass filesystem permissions from macOS or Linux.

Mistake 4: Unsaved changes prevent quitting

Error:

E37: No write since last change (add ! to override)

Fix:

• Save and quit: :wq
• Quit without saving: :q!

Mistake 5: Cancel the command-line prompt

Scenario: You pressed : but changed your mind.

Fix: Press ESC to return to Normal mode.

You’re Done When…

Completion checklist:

• Confirm Vim with vim --version
• Open a file using vim practice.txt
• Enter Insert mode with i
• Type text and return to Normal with ESC
• Save and quit using :wq
• Verify the contents with cat practice.txt
• Practice quitting without saving via :q!

Practice tasks:

Task 1: Repeat the basic workflow

vim again.txt

Steps:

1. Press i
2. Type Second practice file
3. Press Esc
4. Type :wq
5. Press Enter

Task 2: Practice quitting without saving

vim scratch.txt

Steps:

1. Press i
2. Type anything
3. Press Esc
4. Type :q!
5. Press Enter

Next Episode

Once you can install and launch Vim, it’s time to dive into modes and cursor movement.

Vim Series 3: Mastering Modes and Navigation covers Normal/Insert/Visual modes in depth and teaches keyboard-only cursor movement.