LOCATE(1)

📦
version 4.11.0 · 4 versions
, in ubuntu stonking

💖 NAME 💖

okay bestie, meet LOCATE(1) — aka locate — the icon that lists files in databases that match a pattern. 🦋

✨ SYNOPSIS ✨

locate [-d path | --database=path] [-e | -E | --[non-]existing] [-i |
       --ignore-case] [-0 | --null] [-c | --count] [-w | --wholename]
       [-b | --basename] [-l N | --limit=N] [-S | --statistics] [-r |
       --regex] [--regextype R] [--max-database-age D] [-P | -H |
       --nofollow] [-L | --follow] [--version] [-A | --all] [-p |
       --print] [--help] pattern...

🌸 DESCRIPTION 🌸

This page is all about the GNU version of locate, no cap. So here's the vibe: for every pattern you hand it, locate digs through one or more databases of file names and shows you the file names that contain that pattern. 💅

Patterns can hold shell-style metacharacters: *, ?, and []. And lowkey the wild part — these metacharacters do not treat / or . as anything special. So a pattern like foo*bar can match a file name containing foo3/bar, and a pattern like *duck* can match a file name containing lake/.ducky. 🦆 Patterns with metacharacters should be quoted, bestie, so the shell doesn't go and expand them behind your back.

If a pattern is a plain string — like, zero metacharacters — locate shows all the file names in the database that contain that string anywhere. But if a pattern does have metacharacters, locate only shows file names that match the pattern exactly. So basically: metacharacter patterns should usually start with a * and usually end with one too. The exceptions are the patterns you deliberately want to match the beginning or the end of a file name. 🔥

The file name databases contain lists of files that were on the system when the databases were last updated. Your system administrator gets to pick the default database's file name, how often the databases get refreshed, and which directories they hold entries for — see updatedb(1). 👑

If locate's output is headed to a terminal, unusual characters in the output get escaped the same way as for the -print action of the find command. If the output is not going to a terminal, file names are printed exactly as-is. periodt. 💜

🎀 OPTIONS 🎀

  • -0, --null — use ASCII NUL as the separator instead of newline. 🫶
  • -A, --all — only print names that match all the non-option arguments, not the ones matching one or more of them.
  • -b, --basename — a result counts as a match if your pattern matches the final component of the file's name as listed in the database. That final component is what everyone calls the base name. 🌸
  • -c, --count — instead of printing the matched filenames, just print the total number of matches found. (Unless --print (-p) is also there, obviously.) ✨
  • -d path, --database=path — instead of searching the default file name database, search the file name databases in path, which is a colon-separated list of database file names. You can also set the list of databases to search with the LOCATE_PATH environment variable. If both are used, the option wins and overrides the environment variable. Empty elements in path are taken as synonyms for the file name of the default database. And a database can be piped in on standard input by using - as an element of path. If more than one element of path is -, later instances are ignored (and a warning message gets printed). 😭

Heads up: the file name database format changed starting with GNU find and locate version 4.0, so that machines with different byte orderings can share databases. This version of locate can automatically recognize and read databases produced for older versions of GNU locate, or Unix versions of locate or find. Support for the old locate database format will be discontinued in a future release. 💀

  • -e, --existing — only print names that currently exist (instead of names that existed back when the database was created). Careful tho: this can slow the program down a lot if there are many matches in the database. And if you're calling this from inside a program, please note it's possible for the file to get deleted after locate checked that it exists but before you actually use it. 😬
  • -E, --non-existing — only print names that currently do not exist (instead of names that existed when the database was created). Same warning, bestie: this can slow the program down a lot if there are many matches in the database.
  • --help — print a summary of locate's options and exit. bye 👋
  • -i, --ignore-case — ignore case distinctions in both the pattern and the file names.
  • -l N, --limit=N — cap the number of matches at N. And if a limit is set with this option, the number of results printed for the -c option will never be larger than this number.
  • -L, --follow — if you're testing for file existence (with -e or -E), treat broken symbolic links as non-existing. This is the default. 💅
  • --max-database-age D — normally locate warns you when it searches a database more than 8 days old. This option changes that value to something other than 8. The effect of specifying a negative value is undefined. 🚨
  • -m, --mmap — accepted but does nothing, for compatibility with BSD locate.
  • -P, -H, --nofollow — if you're testing for file existence (with -e or -E), treat broken symbolic links as if they were existing files. The -H form is provided purely for similarity with find; using -P is recommended over -H.
  • -p, --print — print search results when they normally wouldn't be printed, because of --statistics (-S) or --count (-c) being present.
  • -r, --regex — treat the pattern given on the command line as a regular expression instead of a glob pattern. These regular expressions work the same way as in emacs, except for the fact that . will match a newline. GNU find uses these same regular expressions. Filenames whose full paths match the specified regular expression get printed (or, with -c, counted). If you want to anchor your regular expression at the ends of the full path name, then — as is usual with regular expressions — use ^ and $ to signify that. 🔥
  • --regextype R — use regular expression dialect R. Supported dialects include findutils-default, posix-awk, posix-basic, posix-egrep, posix-extended, posix-minimal-basic, awk, ed, egrep, emacs, gnu-awk, grep and sed. Peep the Texinfo documentation for a detailed explanation of these dialects. 👑
  • -s, --stdio — accepted but does nothing, for compatibility with BSD locate.
  • -S, --statistics — print various statistics about each locate database and then exit without performing a search — unless non-option arguments are given. For compatibility with BSD, -S is accepted as a synonym for --statistics. However, the output of locate -S is different between the GNU and BSD implementations of locate. 🙈
  • --version — print the version number of locate and exit.
  • -w, --wholename — match against the whole name of the file as listed in the database. This is the default. ⭐

🌈 ENVIRONMENT 🌈

  • LOCATE_PATH — colon-separated list of databases to search. If the value has a leading or trailing colon, or has two colons in a row, you may get results that vary between different versions of locate. 😵‍💫

💫 HISTORY 💫

The locate program started life as the BSD fast find program, contributed to BSD by James A. Woods. It was described in his paper Finding Files Fast, published in Usenix ;login:, Vol 8, No 1, February/March, 1983, pp. 8-10. Back then, when the find program began to assume a default -print action if no action was specified, that changed the interpretation of find pattern. So the BSD developers moved the fast find functionality into locate instead. The GNU implementation of locate appears to be derived from the same code. 🧚

Significant changes to locate, in reverse order:

  • 4.3.7 — Byte-order independent support for old database format
  • 4.3.3 — locate -i supports multi-byte characters correctly; Introduced --max_db_age
  • 4.3.2 — Support for the slocate database format
  • 4.2.22 — Introduced the --all option
  • 4.2.15 — Introduced the --regex option
  • 4.2.14 — Introduced options -L, -P, -H
  • 4.2.12 — Empty items in LOCATE_PATH now indicate the default database
  • 4.2.11 — Introduced the --statistics option
  • 4.2.4 — Introduced --count and --limit
  • 4.2.0 — Glob characters cause matching against the whole file name
  • 4.0 — Introduced the LOCATE02 database format
  • 3.7 — Locate can search multiple databases

💀 BUGS 💀

The locate database correctly handles filenames containing newlines, but only if the system's sort command has a working -z option. If you suspect locate may need to return filenames containing newlines, consider using its --null option instead. 🫶

📢 REPORTING BUGS 📢

GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help>

Report any translation bugs to <https://translationproject.org/team/>

Report any other issue via the form at the GNU Savannah bug tracker: <https://savannah.gnu.org/bugs/?group=findutils>

General topics about the GNU findutils package are discussed at the bug-findutils mailing list: <https://lists.gnu.org/mailman/listinfo/bug-findutils>

Copyright © 1994–2026 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

👀 SEE ALSO 👀

find(1), updatedb(1), xargs(1), glob(3), locatedb(5)

Full documentation <https://www.gnu.org/software/findutils/locate> — or available locally via: info locate

okay that's the whole thing, bestie, you ate 💅✨ this page came from findutils, dated 2020-12-27, and you're literally holding the LOCATE(1) manual page in your hands. go find some files. 🦋💖

📦 where this page comes from
  • ubuntu stonking: locate 4.11.0-2 · GFDL-1.3-or-later-no-invariants OR GFDL-1.3-or-later-no-invariants
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms