## File: README.md

# dirsearch - Web Path Discovery




[](https://github.com/maurosoria/dirsearch/releases)
[](https://github.com/sponsors/maurosoria)
[](https://discord.gg/2N22ZdAJRj)
[](https://twitter.com/_dirsearch)


> An advanced web path brute-forcer

**dirsearch** is being actively developed by [@maurosoria](https://twitter.com/_maurosoria) and [@shelld3v](https://twitter.com/shells3c_).

Join the [Discord server](https://discord.gg/2N22ZdAJRj) to communicate with the team.

## Quick Start

dirsearch requires Python 3.11 or higher.

```sh
git clone https://github.com/maurosoria/dirsearch.git --depth 1
cd dirsearch
python3 dirsearch.py -u https://example.com -e php,html,js
```

You can also install the latest Python stack directly from GitHub with pip:

```sh
pip3 install git+https://github.com/maurosoria/dirsearch.git
dirsearch -u https://example.com -e php,html,js
```

The Rust native backend is opt-in for source installs; see [Installation](docs/installation.md) for the native build steps.

Pre-built PyInstaller binaries and portable folder archives are available on the [Releases page](https://github.com/maurosoria/dirsearch/releases).

## Documentation

The full documentation now lives in [`docs/`](docs/index.md):

- [Installation](docs/installation.md): supported platforms, Python install, release artifacts, and Docker.
- [Usage Guide](docs/usage.md): common scans, recursion, filters, proxies, raw requests, reports, and tips.
- [Wordlists](docs/wordlists.md): `%EXT%`, categories, templates, prefixes, suffixes, and transformations.
- [CLI Options](docs/options.md): complete command-line reference.
- [Configuration](docs/configuration.md): `config.ini` reference.
- [Sessions](docs/sessions.md): save, list, and resume scan sessions.
- [Python API](docs/python-api.md): importable API examples.
- [Building](docs/building.md): PyInstaller, portable builds, Docker images, and GitHub Actions.
- [References](docs/references.md): external tutorials and articles.

## Minimal Examples

```sh
python3 dirsearch.py -u https://target
python3 dirsearch.py -u https://target -e php,html,js
python3 dirsearch.py -u https://target -e php,html,js -w /path/to/wordlist
python3 dirsearch.py -u https://target -r --max-recursion-depth 3
```

Use `python3 dirsearch.py -h` for the full CLI help.

## Python API

dirsearch can also be used from Python code for local automation, MCP servers,
REST wrappers, and agent-controlled scans. The importable API keeps its
configuration in `FuzzerConfig`, so callers do not need to parse CLI flags or
mutate CLI globals.

See [Python API](docs/python-api.md) for examples covering templates, custom
wordlists, callbacks, authenticated sessions, and agent-oriented scan recipes.

## Contributing

Pull requests and feature requests are welcome. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the people who have helped improve dirsearch.

## License

Copyright (C) Mauro Soria (maurosoria@gmail.com)

License: GNU General Public License, version 2.

---

## File: docs/index.md

# dirsearch Documentation

dirsearch is an advanced web path brute-forcer. This documentation is split into focused pages so the repository README can stay concise and the docs can later become the base for a documentation site.

## User Documentation

- [Installation](installation.md): supported platforms, Python installation, release artifacts, and Docker usage.
- [Usage Guide](usage.md): common command examples, recursion, filtering, proxies, raw requests, reports, and practical tips.
- [Wordlists](wordlists.md): extension handling, bundled categories, templates, prefixes, suffixes, and wordlist transformations.
- [CLI Options](options.md): complete command-line option reference.
- [Configuration](configuration.md): `config.ini` behavior and reference.
- [Sessions](sessions.md): saving, listing, and resuming interrupted scans.
- [Python API](python-api.md): using dirsearch from Python automation.

## Maintainer Documentation

- [Building](building.md): PyInstaller builds, portable archives, Docker images, and GitHub Actions workflows.
- [References](references.md): external articles, tutorials, and videos.