Getting started

This is a short tour that takes you from a fresh install to being productive with Projectile in a few minutes. Everything here links into the rest of the manual, where you’ll find the full details.

Install and enable Projectile

Install Projectile from MELPA (see Installation for the other options), then add this to your Emacs configuration:

(projectile-mode +1)
;; Projectile ships no default prefix key, so bind one yourself.
;; Popular choices are `s-p' (macOS) and `C-c p'.
(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)
The rest of this manual writes keybindings as s-p …​; just substitute whatever prefix you picked above.
Pair Projectile with a modern completion UI such as Vertico for a much nicer experience at every prompt. See Completion options.

Open a project

There’s no explicit "open project" step. Just visit any file inside a version-controlled repository, or inside a directory Projectile recognizes as a project (one holding a Gemfile, pom.xml, package.json, and dozens more), and that becomes your current project.

If a directory isn’t detected automatically, drop an empty .projectile file at its root to mark it. See Projects for how detection works.

Your first commands

With a file from the project open, try these:

  • s-p f - jump to any file in the project.

  • s-p p - switch to another project (then pick a file in it).

  • s-p b - switch to another buffer belonging to the project.

  • s-p s g - search the project for some text.

  • s-p t - toggle between an implementation file and its test.

  • s-p m - open the dispatch menu, which lists every Projectile command.

If you can’t recall a binding, s-p m is the one to memorize - the dispatch menu shows everything else.

Where to go next