
dirsearch - Web path discovery
An advanced web path brute-forcer
dirsearch is being actively developed by @maurosoria and @shelld3v
Reach to our Discord server to communicate with the team at best
Table of Contents
Supported Platforms
dirsearch runs on multiple platforms and can be used either via Python or standalone binaries:
| Platform | Python | Standalone Binary |
|---|---|---|
| Linux (x86_64) | Python 3.9+ | dirsearch-linux-amd64 |
| Windows (x64) | Python 3.9+ | dirsearch-windows-x64.exe |
| macOS (Intel) | Python 3.9+ | dirsearch-macos-intel |
| macOS (Apple Silicon) | Python 3.9+ | dirsearch-macos-silicon |
Standalone binaries are self-contained executables that don't require Python installation.
Installation & Usage
Requirement: python 3.9 or higher
Choose one of these installation options:
Install with git:
git clone https://github.com/maurosoria/dirsearch.git --depth 1(RECOMMENDED)Install with ZIP file: Download here
Install with Docker:
docker build -t "dirsearch:v0.4.3" .(more information can be found here)Install with PyPi:
pip3 install dirsearchorpip install dirsearchInstall with Kali Linux:
sudo apt-get install dirsearch(deprecated)
Standalone Binaries
Pre-built standalone binaries are available for all major platforms. These don't require Python to be installed.
Download from Releases
| Platform | Binary Name | Architecture |
|---|---|---|
| Linux | dirsearch-linux-amd64 | x86_64 |
| Windows | dirsearch-windows-x64.exe | x64 |
| macOS Intel | dirsearch-macos-intel | x86_64 |
| macOS Apple Silicon | dirsearch-macos-silicon | ARM64 |
Usage:
Note: Standalone binaries include bundled db/ wordlists and config.ini. Session files are stored in $HOME/.dirsearch/sessions/ when using bundled builds.
Wordlists (IMPORTANT)
Summary:
Wordlist is a text file, each line is a path.
About extensions, unlike other tools, dirsearch only replaces the
%EXT%keyword with extensions from -e flag.For wordlists without
%EXT%(like SecLists), -f | --force-extensions switch is required to append extensions to every word in wordlist, as well as the/.To apply your extensions to wordlist entries that have extensions already, use -O | --overwrite-extensions (Note: some extensions are excluded from being overwritted such as .log, .json, .xml, ... or media extensions like .jpg, .png)
To use multiple wordlists, you can separate your wordlists with commas. Example:
wordlist1.txt,wordlist2.txt.Bundled wordlist categories live in
db/categories/and can be selected with --wordlist-categories. Available:extensions,conf,vcs,backups,db,logs,keys,web,common(useallto include everything).
Wordlist Examples (click to expand)
Examples:
Normal extensions:
Passing asp and aspx as extensions will generate the following dictionary:
Force extensions:
Passing php and html as extensions with -f/--force-extensions flag will generate the following dictionary:
Overwrite extensions:
Passing jsp and jspa as extensions with -O/--overwrite-extensions flag will generate the following dictionary:
Options
Full Options List (click to expand)
Configuration
Configuration File Reference (click to expand)
By default, config.ini inside your dirsearch directory is used as the configuration file but you can select another file via --config flag or DIRSEARCH_CONFIG environment variable.
How to use
Some examples for how to use dirsearch - those are the most common arguments. If you need all, just use the -h argument.
Simple usage
More Usage Examples (click to expand)
Pausing progress
dirsearch allows you to pause the scanning progress with CTRL+C, from here, you can save the progress (and continue later), skip the current target, or skip the current sub-directory.

Recursion
Recursive brute-force is brute-forcing continuously the after of found directories. For example, if dirsearch finds
admin/, it will brute-forceadmin/*(*is where it brute forces). To enable this feature, use -r (or --recursive) flag
You can set the max recursion depth with --max-recursion-depth, and status codes to recurse with --recursion-status
There are 2 more options: --force-recursive and --deep-recursive
Force recursive: Brute force recursively all found paths, not just paths end with
/Deep recursive: Recursive brute-force all depths of a path (
a/b/c=> adda/,a/b/)
If there are sub-directories that you do not want to brute-force recursively, use
--exclude-subdirs
Threads
The thread number (-t | --threads) reflects the number of separated brute force processes. And so the bigger the thread number is, the faster dirsearch runs. By default, the number of threads is 25, but you can increase it if you want to speed up the progress.
In spite of that, the speed still depends a lot on the response time of the server. And as a warning, we advise you to keep the threads number not too big because it can cause DoS (Denial of Service).
Asynchronous
You can switch to asynchronous mode by --async, let dirsearch use coroutines instead of threads to handle concurrent requests.
In theory, asynchronous mode offers better performance and lower CPU usage since it doesn't require switching between different thread contexts. Additionally, pressing CTRL+C will immediately pause progress without needing to wait for threads to suspend.
Prefixes / Suffixes
--prefixes: Add custom prefixes to all entries
Wordlist:
Generated with prefixes:
--suffixes: Add custom suffixes to all entries
Wordlist:
Generated with suffixes:
Blacklist
Inside the db/ folder, there are several "blacklist files". Paths in those files will be filtered from the scan result if they have the same status as mentioned in the filename.
Example: If you add admin.php into db/403_blacklist.txt, whenever you do a scan that admin.php returns 403, it will be filtered from the result.
Filters
Use -i | --include-status and -x | --exclude-status to select allowed and not allowed response status-codes
For more advanced filters: --exclude-sizes, --exclude-texts, --exclude-regexps, --exclude-redirects and --exclude-response
Raw request
dirsearch allows you to import the raw request from a file. The content would be something looked like this:
Since there is no way for dirsearch to know what the URI scheme is, you need to set it using the --scheme flag. By default, dirsearch automatically detects the scheme.
Wordlist formats
Supported wordlist formats: uppercase, lowercase, capitalization
Lowercase:
Uppercase:
Capital:
Exclude extensions
Use -X | --exclude-extensions with an extension list will remove all paths in the wordlist that contains the given extensions
python3 dirsearch.py -u https://target -X jsp
Wordlist:
After:
Scan sub-directories
From an URL, you can scan a list of sub-directories with --subdirs.
Proxies
dirsearch supports SOCKS and HTTP proxy, with two options: a proxy server or a list of proxy servers.
Reports
Supported report formats: simple, plain, json, xml, md, csv, html, sqlite, mysql, postgresql
More example commands
There are more to discover, try yourself!
Session Management
dirsearch supports saving and resuming scan sessions, allowing you to pause a long-running scan and continue it later.
Session Format
Sessions are stored in JSON format (directory-based structure) for human readability and easy inspection. Legacy .pickle/.pkl session files are no longer supported.
Session directory structure:
Saving a Session
When you pause a scan with CTRL+C, you'll be prompted to save the session:
Resuming a Session
Resume a saved session with the -s / --session flag:
Listing Available Sessions
View all resumable sessions with --list-sessions:
This displays:
Session path
Target URL
Remaining targets and directories
Jobs processed
Error count
Last modified time
Custom Sessions Directory
Specify a custom directory to search for sessions:
Default session locations:
Source install:
<dirsearch>/sessions/Bundled binary:
$HOME/.dirsearch/sessions/
Output History
Sessions maintain a history of previous scan outputs, allowing you to review results from interrupted scans. Each resume appends to the output history with timestamps.
Support Docker
Docker Installation & Usage (click to expand)
Install Docker Linux
Install Docker
To use docker you need superuser power
Build Image dirsearch
To create image
dirsearch is the name of the image and v0.4.3 is the version
Using dirsearch
For using
Building from Source
You can build standalone executables using PyInstaller. This creates a single binary file that includes all dependencies.
Requirements
Python 3.9+
PyInstaller 6.3.0+
All dependencies from
requirements.txt
Quick Build
Manual Build (Linux/macOS)
Manual Build (Windows)
Note: Windows uses ; instead of : as the path separator in --add-data.
Build Output
After building:
Linux/macOS:
dist/dirsearchWindows:
dist/dirsearch.exe
The binary includes:
All Python dependencies
db/directory (wordlists, blacklists)config.ini(default configuration)lib/report/(Jinja2 templates for reports)
CI/CD & GitHub Workflows
dirsearch uses GitHub Actions for continuous integration and automated builds.
Available Workflows
| Workflow | Trigger | Description |
|---|---|---|
| Inspection (CI) | Push, PR | Runs tests, linting, and codespell on Python 3.9/3.11 across Ubuntu and Windows |
| PyInstaller Linux | Manual, Workflow call | Builds dirsearch-linux-amd64 binary |
| PyInstaller Windows | Manual, Workflow call | Builds dirsearch-windows-x64.exe binary |
| PyInstaller macOS Intel | Manual, Workflow call | Builds dirsearch-macos-intel binary |
| PyInstaller macOS Silicon | Manual, Workflow call | Builds dirsearch-macos-silicon binary |
| PyInstaller Draft Release | Manual | Builds all platforms and creates a draft GitHub release |
| Docker Image | Push, PR | Builds and tests Docker image |
| CodeQL Analysis | Push, PR, Schedule | Security scanning with GitHub CodeQL |
| Semgrep Analysis | Push, PR | Static analysis with Semgrep |
Running Workflows Manually
PyInstaller builds can be triggered manually from the GitHub Actions tab:
Go to Actions > Select workflow (e.g., "PyInstaller Linux")
Click Run workflow
Download artifacts from the completed run
Creating a Release
To create a new release with all platform binaries:
Go to Actions > PyInstaller Draft Release
Click Run workflow
Enter the tag (e.g.,
v0.4.4)Select target branch
Optionally mark as prerelease
Review and publish the draft release
Build Matrix
The CI workflow tests on:
Python versions: 3.9, 3.11
Operating systems: Ubuntu (latest), Windows (latest)
References
Articles & Tutorials (click to expand)
Comprehensive Guide on Dirsearch by Shubham Sharma
Comprehensive Guide on Dirsearch Part 2 by Shubham Sharma
How to Find Hidden Web Directories with Dirsearch by GeeksforGeeks
GUÍA COMPLETA SOBRE EL USO DE DIRSEARCH by ESGEEKS
How to use Dirsearch to detect web directories by EHacking
dirsearch how to by VK9 Security
Find Hidden Web Directories with Dirsearch by Wonder How To
Brute force directories and files in webservers using dirsearch by Raj Upadhyay
Live Bug Bounty Recon Session on Yahoo (Amass, crts.sh, dirsearch) w/ @TheDawgyg by Nahamsec
Dirsearch to find Hidden Web Directories by Irfan Shakeel
Getting access to 25000 employees details by Sahil Ahamad
Best Tools For Directory Bruteforcing by Shubham Goyal
Discover hidden files & directories on a webserver - dirsearch full tutorial by CYBER BYTES
Tips
The server has requests limit? That's bad, but feel free to bypass it, by randomizing proxy with
--proxy-listWant to find out config files or backups? Try
--suffixes ~and--prefixes .Want to find only folders/directories? Why not combine
--remove-extensionsand--suffixes /!The mix of
--cidr,-F,-qand will reduce most of noises + false negatives when brute-forcing with a CIDRScan a list of URLs, but don't want to see a 429 flood?
--skip-on-status 429will help you to skip a target whenever it returns 429The server contains large files that slow down the scan? You might want to use
HEADHTTP method instead ofGETBrute-forcing CIDR is slow? Probably you forgot to reduce request timeout and request retries. Suggest:
--timeout 3 --retries 1
Contribution
We have been receiving a lot of helps from many people around the world to improve this tool. Thanks so much to everyone who have helped us so far! See CONTRIBUTORS.md to know who they are.
Pull requests and feature requests are welcomed
License
Copyright (C) Mauro Soria ([email protected])
License: GNU General Public License, version 2