# Sherlock Output Formats: Configuring CSV, XLSX, and Text Reports

> Learn how to configure Sherlock output formats like CSV, XLSX, and text reports. Easily generate and manage your Sherlock scan data with command-line flags.

- Repository: [Sherlock/sherlock](https://github.com/sherlock-project/sherlock)
- Tags: how-to-guide
- Published: 2026-03-02

---

**Sherlock supports three primary output formats—plain text, CSV, and XLSX—each activated via dedicated command-line flags defined in [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py).**

When using the `sherlock-project/sherlock` tool to enumerate usernames across social networks, you can export findings in multiple structured formats. Understanding these **Sherlock output formats** and their configuration options enables integration with automated workflows and data analysis pipelines.

## Supported Export Formats

Sherlock implements three distinct export methods within its main entry point, controlled through specific CLI arguments parsed at lines 24-30 of [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py).

### Plain Text (Default)

By default, Sherlock generates `.txt` files without requiring explicit format flags. According to lines 33-42 in [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py), the application automatically assigns filenames using the pattern `{username}.txt`. When querying multiple users, this creates one text file per username in the current working directory.

### CSV Format

For spreadsheet-compatible data, use the `--csv` flag (argument definition at lines 72-76). The implementation block spanning lines 53-95 opens a comma-separated values file, writes a header row, and appends one record per discovered site. This format respects the `--folderoutput` directory path constructed at lines 55-60.

### Excel XLSX Format

Modern Excel workbooks require the `--xlsx` flag (defined at lines 78-83) and the optional `pandas` dependency. The code at lines 96-135 aggregates results into Python lists, constructs a `pandas.DataFrame`, and invokes `DataFrame.to_excel` to generate the final workbook. Without `pandas` installed, this functionality raises an ImportError.

## Output Configuration Options

Beyond selecting formats, Sherlock provides granular control over file destinations and naming conventions.

### Custom File Paths with --output

For single-user queries, override the default `{username}.txt` naming convention using the `--output` or `-o` flag (lines 66-70). This assigns `result_file = args.output` (lines 33-35), directing output to your specified filesystem path regardless of the username queried.

### Directory Organization with --folderoutput

When processing multiple usernames, use `--folderoutput` or `-fo` (lines 60-64) to consolidate results into a single directory. The script automatically creates missing directories via `os.makedirs` (lines 37-39) and prepends this path to all generated filenames, ensuring clean batch operations.

### Explicit Text Generation with --txt

The `--txt` flag (lines 89-94) maintains backward compatibility by forcing text file creation even when CSV or XLSX formats are requested. This triggers the write block at lines 43-52, which specifically handles username output to text files alongside other formats.

## Command-Line Examples

```bash

# Default: Generate USERNAME.txt files

sherlock alice bob

# Single user with custom output path

sherlock -o /tmp/single_user_report.txt alice

# CSV format with dedicated output folder

sherlock --csv -fo ./sherlock_reports alice bob

# Excel workbook (requires pandas)

sherlock --xlsx alice

# Multiple formats simultaneously

sherlock --csv --txt alice

```

## Implementation Details

The export system relies on `QueryResult` and `QueryStatus` objects defined in [`sherlock_project/result.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/result.py), which provide the structured data written to each format. After argument parsing, the main execution loop (lines 24-30) branches to format-specific handlers:

- **Text handling**: Lines 33-52 manage both default output and explicit TXT generation
- **CSV handling**: Lines 53-95 implement comma-separated value writing with header management
- **XLSX handling**: Lines 96-135 convert result lists into pandas DataFrames for Excel export

Each handler checks `args.folderoutput` to determine whether to prepend a custom directory to the generated filename.

## Summary

- Sherlock outputs data in **plain text**, **CSV**, and **XLSX** formats via `--txt`, `--csv`, and `--xlsx` flags
- Use `--output` to specify custom filenames for single-user queries
- Organize batch results using `--folderoutput` or `-fo` with automatic directory creation
- **XLSX generation requires the `pandas` library** installed in your Python environment
- The `--txt` flag ensures text output when simultaneously generating other formats
- All export logic resides in [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py) with specific handlers at lines 33-95

## Frequently Asked Questions

### Does Sherlock support JSON output?

No, the current implementation in [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py) does not include JSON export functionality. The supported formats are limited to plain text (via default behavior or `--txt`), CSV (via `--csv`), and XLSX (via `--xlsx`) as implemented in the master branch.

### Why does XLSX export fail with a ModuleNotFoundError?

Excel output requires the `pandas` library, which is an optional dependency. Install it using `pip install pandas` before invoking the `--xlsx` flag. The code at lines 96-135 explicitly relies on `pandas.DataFrame` and `DataFrame.to_excel` methods to construct the workbook.

### Can I generate multiple format outputs simultaneously?

Yes, flags can be combined to produce multiple file types from a single query. For example, `sherlock --csv --txt alice` generates both `alice.csv` and [`alice.txt`](https://github.com/sherlock-project/sherlock/blob/main/alice.txt). The `--txt` flag ensures text file generation alongside other formats, maintaining backward compatibility as defined at lines 89-94.

### How do I redirect all batch results to a specific folder?

Use the `--folderoutput` or `-fo` flag followed by your target directory path. When scanning multiple usernames, Sherlock automatically creates the directory using `os.makedirs` (lines 37-39) and places all result files inside it, preserving the standard naming conventions for each format.