Skip to content

Troubleshooting

Common issues and fixes. For where to ask, see Support.

Command not found

# Run as a module
python -m folder2md4llms .

# Make sure pipx-installed apps are on PATH
pipx ensurepath

Python version

Requires Python 3.11+:

python --version

Output is too large

Set a budget; this enables smart condensing:

folder2md . --limit 80000t

For more aggressive reduction, set token_budget_strategy: aggressive in folder2md.yaml.

Too many (or too few) files included

Filtering is done with ignore files, not flags:

# Scaffold an ignore file, then edit it
folder2md --init-ignore

.gitignore is honoured by default. Add anything else you want dropped to .folder2md_ignore. Files above 100MB are skipped; lower max_file_size in folder2md.yaml if needed.

Document conversion problems

Document conversion depends on optional extras. If a PDF/DOCX/XLSX fails to convert, install the relevant libraries:

pip install python-docx openpyxl pypdf

To skip a problematic type, add its extension to .folder2md_ignore, or set convert_docs: false in folder2md.yaml.

See what is happening

folder2md . --verbose

Reporting a problem

Open an issue with:

  • folder2md --version
  • python --version
  • the command you ran and the full error output
  • minimal steps to reproduce

GitHub Issues