Projectile for Emacs: project-level navigation without leaving the minibuffer

The problem Projectile solves: Emacs has no notion of a project

Emacs treats files and buffers as the unit of work. A repository is not a first-class object, so commands like find-file, switch-to-buffer and grep operate on the whole filesystem or on whatever buffer list you have accumulated. If you keep three checkouts open, buffer switching becomes a memory exercise and project-wide search means typing a path prefix every time.

Projectile adds that missing layer. Its README describes it as "a project interaction library for Emacs" that "provides a powerful set of features operating at the project level, as well as simple heuristics to identify projects." The audience is anyone editing code in Emacs across more than one directory: backend developers, polyglot monorepo inhabitants, and people who switch between a library and its consumers several times an hour.

The feature list is deliberately broad rather than deep. Jumping to a file ranked by frecency, jumping to a project buffer, finding a test, toggling between a header and its implementation, toggling between code and its spec file, switching between known projects, killing all project buffers, searching and replacing across a project, finding references through xref, and running named tasks. None of these is unique to Projectile; the value is that they share one project definition and one keymap.

How Projectile decides what a project is

Everything downstream depends on project detection, and Projectile's approach is heuristic. It looks for markers (version control directories, build files, and similar signals) to decide that a directory is a project root, rather than asking a server or reading a registry. The README frames this as a design goal: portability, meaning features that work "without introducing external dependencies (when feasible)."

That portability is visible in the file-finding implementation. The README states that finding project files has "a portable implementation written in pure Emacs Lisp without the use of GNU find (but for performance's sake an indexing mechanism backed by external commands exists as well)." So there are two paths: a pure-Elisp walk that works anywhere Emacs runs, and an optional index that calls out to external commands and is faster on large trees. The trade-off is explicit in the README's own phrasing. The portable path has no dependency cost and pays in speed; the indexed path is quicker and assumes those commands exist on the machine.

Automatic discovery is separate from detection. The variable projectile-project-search-path tells Projectile where to look for projects so they appear in the switch-project list without being opened first. Monorepos get a second layer on top: the documentation describes subprojects, which let you scope file finding, building and testing to one module inside a larger repository rather than the whole thing.

Two integration points matter for how Projectile sits in a modern Emacs. It reads through completing-read, so the completion front end is your choice rather than the library's. And it integrates with the built-in project.el library, which means it does not force you to abandon Emacs's own project facilities.

Installing Projectile and running a first project-wide search

Projectile ships on the community package archives, so installation goes through package.el, the built-in package manager. The README gives the interactive command:

M-x package-install RET projectile RET

Debian and Ubuntu users have a distribution route instead. The README states that users of Debian 9 or later or Ubuntu 16.04 or later may run apt-get install elpa-projectile. That path pins you to whatever version the distribution ships, which will lag the archives.

After installation, enable the global minor mode and bind the command map. The README suggests these prefixes, and notes they are only a suggestion:

(projectile-mode +1)
;; Recommended keymap prefix on macOS
(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map)
;; Recommended keymap prefix on Windows/Linux
(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)

With the mode on, open a file inside one of your repositories and press C-c p f to jump to a file in that project. The README's basic usage section says exactly this: enable projectile-mode, open a file in one of your projects, and type a command such as C-c p f. You should see a completing-read prompt listing files from the project root, not from your current directory. If the list looks like your home directory, Projectile did not recognize the buffer as belonging to a project, which usually means the root marker it expects is missing.

For project-wide search, the README points at grep and ripgrep with a "native reviewable results UI," and replacement gets a before/after preview you review before applying. Those two commands are where the review step earns its keep: you see the matches or the diff before anything is written.

Completion quality is a configuration decision, not an installation one. The README recommends a modern completion setup such as vertico paired with consult, marginalia and orderless, or the built-in fido-vertical-mode, and links to the configuration section of the documentation for details.

The completion-system break in Projectile 3.0

The most consequential compatibility fact in the README is a removal, not an addition. As of Projectile 3.0, the dedicated ido, ivy and helm completion systems were removed, along with the old projectile-completion-system values, in favor of completing-read. The README adds that existing setups keep working through your completion UI, and that helm-projectile and counsel-projectile are unaffected.

Read that carefully before upgrading from a 2.x configuration. If your init file sets projectile-completion-system to something like ivy or helm, that variable no longer does what it did. The packages built on top of those systems still work, but the coupling moved from Projectile's configuration to your completion framework. The practical consequence is that Projectile's own surface got smaller and the completion behavior now depends on whatever completing-read implementation is active.

This is a defensible simplification. Maintaining per-framework glue inside a project library duplicates work that Vertico, Consult and friends already do better. It also means a bug in the completion display is no longer Projectile's to fix. The cost is that anyone who pinned behavior to the old variable has to change their config, and the README does not document a migration shim, only the note that existing setups keep working via the completion UI.

Where Projectile is the wrong tool

Projectile is not a build system. It runs project commands and tasks, including the npm scripts, Make targets and justfile recipes a project already defines, but it does not define a build graph, resolve dependencies or cache artifacts. If your build orchestration needs those things, Projectile is a launcher in front of tools that do them, nothing more.

It is not a language server either. Finding references goes through xref internally, so the precision of a reference search is whatever the xref backend provides. For a language with a real LSP backend that is fine; for a language where xref falls back to a text search, you get text-search quality with a nicer interface.

Test-at-point has a version floor. The README attributes it to tree-sitter and Emacs 29 or later. On Emacs 28 or older, that particular command is unavailable regardless of configuration, so a team standardized on an older Emacs should not plan around it.

The heuristics that make detection portable also make it fallible. A directory tree with no recognizable root marker will not be treated as a project, and a nested repository may be seen as one project or two depending on where markers sit. The README does not document rollback behavior for the replace command, so treat the before/after preview as the safety mechanism it is rather than assuming an undo path exists.

Finally, the maintenance picture is uneven by channel. The repository is not archived and the last push was on 2026-09-16, with releases v3.4.0 on 2026-08-10, v3.3.0 on 2026-07-27 and v3.2.1 on 2026-07-13. That is an active release cadence on master. The distribution package is a different story, since it depends on when your distribution last rebuilt it.

Projectile compared with Emacs's built-in project.el

The obvious alternative is project.el, which ships with Emacs and solves the same core problem: giving Emacs a project abstraction. Projectile's README lists integration with project.el as a feature, so the two are not mutually exclusive, and that integration is the most useful thing to understand before choosing.

The difference in approach is scope and history. project.el is minimal by design: it defines projects and a small command set, and it assumes you will add what you need. Projectile is a decade-old library with a much wider command surface, from frecency-ranked file jumping to per-project sessions with tab-bar workspaces that restore window layouts and buffers across restarts. The README also notes a third-party extension ecosystem on MELPA, which project.el does not have in the same form.

So the choice is not about correctness. Use project.el if you want the smallest possible surface and no external package. Use Projectile if you want the wider set of project-level commands and are willing to install a package and configure a keymap. Because Projectile integrates with project.el, you can also run both and let each handle what it does best, at the cost of two overlapping command sets and two sets of keybindings to keep straight.

Licence and the cost of keeping Projectile current

Projectile is licensed GPL-3.0, and the repository carries a LICENSE file alongside the README. For Emacs packages this is the conventional choice, and it is compatible with the way package.el distributes Emacs Lisp. It does mean that if you fork Projectile and distribute a modified version, the GPL's terms apply to that distribution. That is a general observation about the licence identifier, not legal advice; read the licence text if your situation is unusual.

Upgrade cost has two components. The first is the package source. Projectile is available on NonGNU ELPA, MELPA Stable and MELPA, and those archives do not move in lockstep: MELPA Stable tracks tagged releases while MELPA follows the default branch. If you install from MELPA, a package-upgrade can pull in unreleased changes from master. If you install from MELPA Stable, you get the tagged releases such as v3.4.0. Choosing one deliberately is cheaper than discovering which one you are on after a break.

The second component is configuration drift. The 3.0 completion-system removal is the clearest example: a config that survived years of upgrades stopped meaning what it said. Projectile's own release notes and CHANGELOG.md are the places to check before a major upgrade, since the README documents current behavior rather than migration paths. The repository also ships an Eldev file, which is the build tool used for its own development and tests, not something an end user needs to install.

Editorial conclusion

Adopt Projectile if you keep several repositories open in Emacs and want file jumping, test toggling and project-wide search behind a single keymap, and if you are willing to run a recent Emacs with a completing-read UI such as Vertico or fido-vertical-mode. Do not adopt it expecting a build system, a language server or a dependency resolver; it shells out to your existing tools for search and tasks and leaves dependency management alone. Before committing, check that your Emacs version supports the features you want (tree-sitter test-at-point needs Emacs 29 or later), confirm which package archive you are installing from since MELPA and MELPA Stable track different release cadences, and decide whether the default C-c p prefix collides with a binding you already use.

Frequently asked questions

Official sources

1. bbatsov/projectile on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases