Repository files navigation

ripgrep is a line-oriented search tool that recursively searches the currentdirectory for a regex pattern. By default, ripgrep will respect gitignore rulesand automatically skip hidden files/directories and binary files. (To disableall automatic filtering by default, userg -uuu.) ripgrep has first classsupport on Windows, macOS and Linux, with binary downloads available foreveryrelease. ripgrep is similar toother popular search tools like The Silver Searcher, ack and grep.

Dual-licensed under MIT or theUNLICENSE.

Please see theCHANGELOG for a release history.

• Installation
• User Guide
• Frequently Asked Questions
• Regex syntax
• Configuration files
• Shell completions
• Building
• Translations

This example searches the entireLinux kernel source tree(after runningmake defconfig && make -j8) for[A-Z]+_SUSPEND, whereall matches must be words. Timings were collected on a system with an Inteli9-12900K 5.2 GHz.

Please remember that a single benchmark is never enough! See myblog post on ripgrepfor a very detailed comparison with more benchmarks and analysis.

Here's another benchmark on the same corpus as above that disregards gitignorefiles and searches with a whitelist instead. The corpus is the same as in theprevious benchmark, and the flags passed to each command ensure that they aredoing equivalent work:

Now we'll move to searching on single large file. Here is a straight-upcomparison between ripgrep, ugrep and GNU grep on a file cached in memory(~13GB,OpenSubtitles.raw.en.gz, decompressed):

In the above benchmark, passing the-n flag (for showing line numbers)increases the times to1.664s for ripgrep and9.484s for GNU grep. ugreptimes are unaffected by the presence or absence of-n.

Beware of performance cliffs though:

And performance can drop precipitously across the board when searching bigfiles for patterns without any opportunities for literal optimizations:

Finally, high match counts also tend to both tank performance and smoothout the differences between tools (because performance is dominated by howquickly one can handle a match and not the algorithm used to detect the match,generally speaking):

• It can replace many use cases served by other search toolsbecause it contains most of their features and is generally faster. (Seethe FAQ for more details on whether ripgrep can trulyreplace grep.)
• Like other tools specialized to code search, ripgrep defaults torecursive search and doesautomaticfiltering. Namely, ripgrep won't search filesignored by your.gitignore/.ignore/.rgignore files, it won't searchhidden files and it won't search binary files. Automatic filtering can bedisabled withrg -uuu.
• ripgrep cansearch specific types of files.For example,rg -tpy foo limits your search to Python files andrg -Tjs foo excludes JavaScript files from your search. ripgrep can be taught aboutnew file types with custom matching rules.
• ripgrep supports many features found ingrep, such as showing the contextof search results, searching multiple patterns, highlighting matches withcolor and full Unicode support. Unlike GNU grep, ripgrep stays fast whilesupporting Unicode (which is always on).
• ripgrep has optional support for switching its regex engine to use PCRE2.Among other things, this makes it possible to use look-around andbackreferences in your patterns, which are not supported in ripgrep's defaultregex engine. PCRE2 support can be enabled with-P/--pcre2 (use PCRE2always) or--auto-hybrid-regex (use PCRE2 only if needed). An alternativesyntax is provided via the--engine (default|pcre2|auto) option.
• ripgrep hasrudimentary support for replacements,which permit rewriting output based on what was matched.
• ripgrep supportssearching files in text encodingsother than UTF-8, such as UTF-16, latin-1, GBK, EUC-JP, Shift_JIS and more.(Some support for automatically detecting UTF-16 is provided. Other textencodings must be specifically specified with the-E/--encoding flag.)
• ripgrep supports searching files compressed in a common format (brotli,bzip2, gzip, lz4, lzma, xz, or zstandard) with the-z/--search-zip flag.
• ripgrep supportsarbitrary input preprocessing filterswhich could be PDF text extraction, less supported decompression, decrypting,automatic encoding detection and so on.
• ripgrep can be configured via aconfiguration file.

In other words, use ripgrep if you like speed, filtering by default, fewerbugs and Unicode support.

Despite initially not wanting to add every feature under the sun to ripgrep,over time, ripgrep has grown support for most features found in other filesearching tools. This includes searching for results spanning across multiplelines, and opt-in support for PCRE2, which provides look-around andbackreference support.

At this point, the primary reasons not to use ripgrep probably consist of oneor more of the following:

• You need a portable and ubiquitous tool. While ripgrep works on Windows,macOS and Linux, it is not ubiquitous and it does not conform to anystandard such as POSIX. The best tool for this job is good old grep.
• There still exists some other feature (or bug) not listed in this README thatyou rely on that's in another tool that isn't in ripgrep.
• There is a performance edge case where ripgrep doesn't do well where anothertool does do well. (Please file a bug report!)
• ripgrep isn't possible to install on your machine or isn't available for yourplatform. (Please file a bug report!)

Generally, yes. A large number of benchmarks with detailed analysis for each isavailable on my blog.

Summarizing, ripgrep is fast because:

• It is built on top ofRust's regex engine.Rust's regex engine uses finite automata, SIMD and aggressive literaloptimizations to make searching very fast. (PCRE2 support can be opted intowith the-P/--pcre2 flag.)
• Rust's regex library maintains performance with full Unicode support bybuilding UTF-8 decoding directly into its deterministic finite automatonengine.
• It supports searching with either memory maps or by searching incrementallywith an intermediate buffer. The former is better for single files and thelatter is better for large directories. ripgrep chooses the best searchingstrategy for you automatically.
• Applies your ignore patterns in.gitignore files using aRegexSet.That means a single file path can be matched against multiple glob patternssimultaneously.
• It uses a lock-free parallel recursive directory iterator, courtesy ofcrossbeam andignore.

Andy Lester, author ofack, has published anexcellent table comparing the features of ack, ag, git-grep, GNU grep andripgrep:https://beyondgrep.com/feature-comparison/

Note that ripgrep has grown a few significant new features recently thatare not yet present in Andy's table. This includes, but is not limited to,configuration files, passthru, support for searching compressed files,multiline search and opt-in fancy regex support via PCRE2.

If you'd like to try ripgrep before installing, there's an unofficialplayground and aninteractivetutorial.

If you have any questions about these, please open an issue in thetutorialrepo.

The binary name for ripgrep isrg.

Archives of precompiled binaries for ripgrep are available for Windows,macOS and Linux. Linux andWindows binaries are static executables. Users of platforms not explicitlymentioned below are advised to download one of these archives.

If you're amacOS Homebrew or aLinuxbrew user, then you can installripgrep from homebrew-core:

$ brew install ripgrep

If you're aMacPorts user, then you can install ripgrep from theofficial ports:

$ sudo port install ripgrep

If you're aWindows Chocolatey user, then you can install ripgrep from theofficial repo:

$ choco install ripgrep

If you're aWindows Scoop user, then you can install ripgrep from theofficial bucket:

$ scoop install ripgrep

If you're aWindows Winget user, then you can install ripgrep from thewinget-pkgsrepository:

$ winget install BurntSushi.ripgrep.MSVC

If you're anArch Linux user, then you can install ripgrep from the official repos:

$ sudo pacman -S ripgrep

If you're aGentoo user, you can install ripgrep from theofficial repo:

$ sudo emerge sys-apps/ripgrep

If you're aFedora user, you can install ripgrep from officialrepositories.

$ sudo dnf install ripgrep

If you're anopenSUSE user, ripgrep is included inopenSUSE TumbleweedandopenSUSE Leap since 15.1.

$ sudo zypper install ripgrep

If you're aRHEL/CentOS 7/8 user, you can install ripgrep fromcopr:

$ sudo yum install -y yum-utils$ sudo yum-config-manager --add-repo=https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/repo/epel-7/carlwgeorge-ripgrep-epel-7.repo$ sudo yum install ripgrep

If you're aNix user, you can install ripgrep fromnixpkgs:

$ nix-env --install ripgrep

If you're aFlox user, you can install ripgrep as follows:

$ flox install ripgrep

If you're aGuix user, you can install ripgrep from the officialpackage collection:

$ guix install ripgrep

If you're aDebian user (or a user of a Debian derivative likeUbuntu),then ripgrep can be installed using a binary.deb file provided in eachripgrep release.

$ curl -LO https://github.com/BurntSushi/ripgrep/releases/download/14.1.0/ripgrep_14.1.0-1_amd64.deb$ sudo dpkg -i ripgrep_14.1.0-1_amd64.deb

If you run Debian stable, ripgrep isofficially maintained byDebian, although its version maybe older than thedeb package available in the previous step.

$ sudo apt-get install ripgrep

If you're anUbuntu Cosmic (18.10) (or newer) user, ripgrep isavailable using the samepackaging as Debian:

$ sudo apt-get install ripgrep

(N.B. Various snaps for ripgrep on Ubuntu are also available, but none of themseem to work right and generate a number of very strange bug reports that Idon't know how to fix and don't have the time to fix. Therefore, it is nolonger a recommended installation option.)

If you're anALT user, you can install ripgrep from theofficial repo:

$ sudo apt-get install ripgrep

If you're aFreeBSD user, then you can install ripgrep from theofficial ports:

$ sudo pkg install ripgrep

If you're anOpenBSD user, then you can install ripgrep from theofficial ports:

$ doas pkg_add ripgrep

If you're aNetBSD user, then you can install ripgrep frompkgsrc:

$ sudo pkgin install ripgrep

If you're aHaiku x86_64 user, then you can install ripgrep from theofficial ports:

$ sudo pkgman install ripgrep

If you're aHaiku x86_gcc2 user, then you can install ripgrep from thesame port as Haiku x86_64 using the x86 secondary architecture build:

$ sudo pkgman install ripgrep_x86

If you're aVoid Linux user, then you can install ripgrep from theofficial repository:

$ sudo xbps-install -Syv ripgrep

If you're aRust programmer, ripgrep can be installed withcargo.

• Note that the minimum supported version of Rust for ripgrep is1.72.0,although ripgrep may work with older versions.
• Note that the binary may be bigger than expected because it contains debugsymbols. This is intentional. To remove debug symbols and therefore reducethe file size, runstrip on the binary.

$ cargo install ripgrep

Alternatively, one can usecargo binstall to install a ripgrepbinary directly from GitHub:

$ cargo binstall ripgrep

ripgrep is written in Rust, so you'll need to grab aRust installation in order to compile it.ripgrep compiles with Rust 1.72.0 (stable) or newer. In general, ripgrep tracksthe latest stable release of the Rust compiler.

To build ripgrep:

$ git clone https://github.com/BurntSushi/ripgrep$ cd ripgrep$ cargo build --release$ ./target/release/rg --version0.1.3

NOTE: In the past, ripgrep supported asimd-accel Cargo feature whenusing a Rust nightly compiler. This only benefited UTF-16 transcoding.Since it required unstable features, this build mode was prone to breakage.Because of that, support for it has been removed. If you want SIMDoptimizations for UTF-16 transcoding, then you'll have to petition theencoding_rs project to use stableAPIs.

Finally, optional PCRE2 support can be built with ripgrep by enabling thepcre2 feature:

$ cargo build --release --features 'pcre2'

Enabling the PCRE2 feature works with a stable Rust compiler and willattempt to automatically find and link with your system's PCRE2 library viapkg-config. If one doesn't exist, then ripgrep will build PCRE2 from sourceusing your system's C compiler and then statically link it into the finalexecutable. Static linking can be forced even when there is an available PCRE2system library by either building ripgrep with the MUSL target or by settingPCRE2_SYS_STATIC=1.

ripgrep can be built with the MUSL target on Linux by first installing the MUSLlibrary on your system (consult your friendly neighborhood package manager).Then you just need to add MUSL support to your Rust toolchain and rebuildripgrep, which yields a fully static executable:

$ rustup target add x86_64-unknown-linux-musl$ cargo build --release --target x86_64-unknown-linux-musl

Applying the--features flag from above works as expected. If you want tobuild a static executable with MUSL and with PCRE2, then you will need to havemusl-gcc installed, which might be in a separate package from the actualMUSL library, depending on your Linux distribution.

ripgrep is relatively well-tested, including both unit tests and integrationtests. To run the full test suite, use:

$ cargo test --all

from the repository root.

• delta is a syntax highlightingpager that supports therg --json output format. So all you need to do tomake it work isrg --json pattern | delta. Seedelta's manual section ongrep for more details.

For reporting a security vulnerability, pleasecontact Andrew Gallant.The contact page has my email address and PGP public key if you wish to send anencrypted message.

The following is a list of known translations of ripgrep's documentation. Theseare unofficially maintained and may not be up to date.

• Chinese
• Spanish