Usage Guide

These examples cover the most common arguments. Use python3 dirsearch.py -h for the complete option list.

Simple Usage

python3 dirsearch.py -u https://target

python3 dirsearch.py -e php,html,js -u https://target

python3 dirsearch.py -e php,html,js -u https://target -w /path/to/wordlist

Pausing Progress

dirsearch allows you to pause scanning with CTRL+C. From there, you can save progress and continue later, skip the current target, or skip the current sub-directory.

See Sessions for session save and resume behavior.

Recursion

Recursive brute-force continues scanning inside discovered directories. For example, if dirsearch finds admin/, it will brute-force admin/*.

Enable recursion with -r or --recursive:

python3 dirsearch.py -e php,html,js -u https://target -r

Set maximum recursion depth and status codes:

python3 dirsearch.py -e php,html,js -u https://target -r --max-recursion-depth 3 --recursion-status 200-399

Additional recursion options:

• --force-recursive: recursively brute-force all found paths, not just paths ending with /.
• --deep-recursive: recursively brute-force all depths of a path, such as a/b/c -> a/, a/b/.

Exclude sub-directories from recursive scans:

python3 dirsearch.py -e php,html,js -u https://target -r --exclude-subdirs image/,media/,css/

Threads

The thread count (-t or --threads) controls the number of separated brute-force processes. The default is 25.

Higher thread counts can make scans faster, but speed still depends on server response time. Avoid excessive thread counts because they can cause denial of service.

python3 dirsearch.py -e php,htm,js,bak,zip,tgz,txt -u https://target -t 20

Asynchronous Mode

Asynchronous mode is the default runtime on Python 3.11 and newer. In this mode, dirsearch uses coroutines instead of threads for concurrent requests.

Asynchronous mode can offer better performance and lower CPU usage because it avoids switching between thread contexts. Pressing CTRL+C also pauses progress immediately without waiting for threads to suspend.

The synchronous Python stack and the native request backend remain available for compatibility and benchmarking. Use --sync to force the synchronous Python stack. Use --request-backend native to select the native backend; dirsearch will run that backend without async mode unless --async is explicitly supplied, which is rejected because the native backend has its own scheduler.

Blacklists

The db/ folder contains blacklist files. Paths in those files are filtered from scan results when they return the status code referenced in the filename.

For example, if you add admin.php to db/403_blacklist.txt, any admin.php result with status 403 will be filtered from output.

Filters

Use -i / --include-status and -x / --exclude-status to include or exclude response status codes.

dirsearch also performs automatic wildcard and soft-404 calibration. You normally do not need to tune this, but --auto-calibration forces extra calibration samples from the beginning when a target is especially noisy.

python3 dirsearch.py -e php,html,js -u https://target --exclude-sizes 1B,243KB

Response size filters accept raw bytes without a suffix or readable units such as B, KB, MB, and GB. The same format works for --exclude-sizes, --min-response-size, and --max-response-size.

python3 dirsearch.py -e php,html,js -u https://target --exclude-text "403 Forbidden"

python3 dirsearch.py -e php,html,js -u https://target --exclude-regex "^Error$"

python3 dirsearch.py -e php,html,js -u https://target --exclude-redirect "https://(.*).okta.com/*"

python3 dirsearch.py -e php,html,js -u https://target --exclude-response /error.html

Advanced ffuf/wfuzz-style filters are available as opt-in controls, not as the main discovery model. For example:

python3 dirsearch.py -u https://target --match-status 200-299 --filter-regex "not found"

Response headers can also be used in advanced filters. Header text matching is case-insensitive; header regex matching uses regular expressions:

python3 dirsearch.py -u https://target --filter-header "x-cache: fallback"
python3 dirsearch.py -u https://target --match-header-regex "etag: W/.+"

Raw Requests

dirsearch can import a raw request from a file:

GET /admin HTTP/1.1
Host: admin.example.com
Cache-Control: max-age=0
Accept: */*

Since dirsearch cannot always infer the URI scheme from a raw request, set it with --scheme when needed. By default, dirsearch automatically detects the scheme.

Scan Sub-Directories

Use --subdirs to scan a list of sub-directories from a URL:

python3 dirsearch.py -e php,html,js -u https://target --subdirs /,admin/,folder/

Proxies

dirsearch supports SOCKS and HTTP proxies. You can provide one proxy or a file containing multiple proxies.

python3 dirsearch.py -e php,html,js -u https://target --proxy 127.0.0.1:8080

python3 dirsearch.py -e php,html,js -u https://target --proxy socks5://10.10.0.1:8080

python3 dirsearch.py -e php,html,js -u https://target --proxies-file proxyservers.txt

Reports

Supported report formats: simple, plain, json, xml, md, csv, html, sqlite, mysql, and postgresql.

python3 dirsearch.py -e php -l URLs.txt --output-formats plain --output-file report.txt

python3 dirsearch.py -e php -u https://target --output-formats html --output-file target.html

More Examples

cat urls.txt | python3 dirsearch.py --stdin

python3 dirsearch.py -u https://target --max-time 360

python3 dirsearch.py -u https://target --auth admin:pass --auth-type basic

python3 dirsearch.py -u https://target --headers-file rate-limit-bypasses.txt

Tips

• If the server has request limits, use proxy randomization with --proxies-file.
• To find config files or backups, try --suffixes ~ and --prefixes ..
• To focus on folder-like candidates, combine directory-focused wordlists with suffixes such as --suffixes /.
• The mix of --cidr, -F, and -q can reduce noise and false negatives when brute-forcing a CIDR.
• To avoid a flood of 429 results while scanning a URL list, use --skip-on-status 429.
• If large server responses slow down the scan, consider the HEAD HTTP method instead of GET.
• If CIDR brute-forcing is slow, reduce request timeout and retries. Suggested values: --timeout 3 --retries 1.