Guide · Open source
How to use subfinder: passive subdomain discovery guide
Updated · written with AI from the project's own documentation and checked against our catalogue data
Subfinder is a command-line tool that lists subdomains for a website, such as blog.example.com or api.example.com for example.com. It works passively, querying online data sources instead of probing the target's servers. This guide shows you how to install it, run it on a domain, filter the output and set up the configuration it uses.
subfinderprojectdiscovery/subfinder · ★ 14.7k · MIT Install options & downloads Quick start
- 1Check Go is installed. Subfinder requires go1.26.10 to install successfully. Confirm your Go version before you start.
- 2Install subfinder. Run the go install command from the README to fetch the latest version of subfinder.
- 3View the help. Run subfinder -h to see all flags and sources.
- 4Run a first search. Run subfinder -d with a domain you are authorized to test.
- 5Save results. Use -o to write output to a file, or -oJ for JSONL format.
- 6Add API keys. Configure provider settings so that sources requiring keys can return results.
- 7Refine output. Use -match, -filter, -match-regex or -filter-regex to narrow the list.
What subfinder does and does not do
Subfinder is a subdomain discovery tool that returns subdomains using passive online sources. It is built to do one thing: passive subdomain enumeration.
Because it is passive, it queries online data sources rather than directly probing the target's servers. The project describes this model as fast and lightweight.
It is not a vulnerability scanner. The README describes only subdomain discovery.
- Good for: authorized reconnaissance, bug bounty target mapping, OSINT on public footprints, and checking your own domain's subdomains.
- Not for: vulnerability checks, or users who want results with no API keys and no terminal use.
Install subfinder with Go
Subfinder requires go1.26.10 to install successfully. If you have Go, run the install command from the README to get the latest version.
The project docs list other install methods at docs.projectdiscovery.io/tools/subfinder/install.
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latestRun your first subdomain search
Pass a domain with the -d flag. To see every switch the tool supports, run the help command first.
Use -silent to show only the subdomains in the output, which is useful when piping results into other tools.
- -d: domain to find subdomains for
- -dL: file containing a list of domains
- -o: file to write output to
- -oJ: write output in JSONL format
- -silent: show only subdomains
subfinder -h
subfinder -d example.com
subfinder -d example.com -silentChoose sources and control rate limits
Use -s to pick specific sources, for example -s crtsh,github. Use -ls to list all available sources. The -all flag uses every source but is noted as slow in the help text. Use -es to exclude sources.
Rate-limit flags control how many HTTP requests are sent per second. -rl sets a global limit and -rls sets per-provider limits.
subfinder -d example.com -s crtsh,github
subfinder -ls
subfinder -d example.com -rl 10Filter the output with regular expressions
Use -match and -filter for subdomain names, and -match-regex and -filter-regex for Go regular expressions. Regex patterns can be given on the command line or in a file, one per line.
- -match / -m: keep only matching subdomains
- -filter / -f: drop matching subdomains
- -match-regex and -filter-regex: Go regular expressions
subfinder -d example.com -match-regex '^(api|web)[0-9]{1,3}\.' -filter-regex '(^|\.)dev\.'Set up API keys and configuration
Subfinder can run right after installation, but many sources require API keys to work well. The README links to the post-install configuration section of the docs for setup.
Subfinder reads config.yaml and provider-config.yaml from default paths under $CONFIG/subfinder. You can override these with the -config and -pc flags, or with the environment variables SUBFINDER_CONFIG and SUBFINDER_PROVIDER_CONFIG.
export SUBFINDER_CONFIG=/path/to/config.yaml
export SUBFINDER_PROVIDER_CONFIG=/path/to/provider-config.yamlWhat people use it for
- Listing subdomains of your own domain to see what is publicly visible.
- Mapping the subdomains of an authorized bug bounty target before deeper testing.
- Collecting public subdomain data for an OSINT review of an organization.
- Feeding a list of domains from a file with -dL into a larger workflow.
Frequently asked questions
Is subfinder free to use?
Subfinder is released under the MIT licence, according to the project's listing. Some of the data sources it queries require API keys, which the README says are needed for good results.
What do I need to install subfinder?
The README says subfinder requires go1.26.10 to install successfully. You install it with the go install command shown in the README.
Does subfinder scan for vulnerabilities?
No. The README describes subfinder as built for passive subdomain enumeration only, and it does not describe vulnerability checks.
Does subfinder work without API keys?
It can be used right after installation, but the README says many sources require API keys to work. Results may be limited without them.
What are the alternatives to subfinder?
Comparable projects listed for this tool include Amass, Sublist3r, assetfinder and findomain.
Why does subfinder return no results or fail?
The README does not cover specific troubleshooting. Check that your Go version matches the stated requirement, that you have set up any needed API keys, and use -v for verbose output.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Subfinder suits security testers, bug bounty hunters, OSINT researchers and developers who are comfortable in a terminal and need a fast passive list of subdomains. Pick something else if you need a vulnerability scanner or a tool that works fully without API keys and a command line.
Install options & downloads