Installation¶

Folder2MD4LLMs can be installed in several ways. Choose the method that works best for your system and workflow.

Python Package (Recommended)¶

The easiest way to install Folder2MD4LLMs is using Python's package managers:

Using pipx (Recommended)¶

# Install pipx if you don't have it
python -m pip install --user pipx
python -m pipx ensurepath

# Install folder2md4llms
pipx install folder2md4llms

# Verify installation
folder2md --help

Using pip¶

# Install globally
pip install folder2md4llms

# Or in a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows WSL2: same as Linux
pip install folder2md4llms

Package Managers¶

Homebrew (macOS)¶

# Add the HenriquesLab tap
brew tap henriqueslab/folder2md4llms

# Install folder2md4llms
brew install folder2md4llms

# Verify installation
folder2md --version

Windows Users¶

For Windows users, we recommend using WSL2 (Windows Subsystem for Linux) for the best compatibility and performance:

# Install WSL2 first (run in PowerShell as Administrator)
wsl --install -d Ubuntu-22.04

# Then follow the Linux installation instructions within WSL2

This provides better compatibility than native Windows installation.

Container Installation¶

Docker¶

# Pull the image
docker pull ghcr.io/henriqueslab/folder2md4llms:latest

# Run folder2md4llms
docker run --rm -v $(pwd):/workspace ghcr.io/henriqueslab/folder2md4llms:latest /workspace

Create an alias for easier use:¶

alias folder2md='docker run --rm -v $(pwd):/workspace ghcr.io/henriqueslab/folder2md4llms:latest'

Development Installation¶

For contributors or users who want the latest features:

# Clone the repository
git clone https://github.com/HenriquesLab/folder2md4llms.git
cd folder2md4llms

# Install with uv (recommended)
uv sync --all-extras

# Or with pip
pip install -e ".[dev]"

# Verify installation
folder2md --help

Verification¶

After installation, verify that Folder2MD4LLMs is working correctly:

# Check version
folder2md --version

# Check help
folder2md --help

# Test basic functionality
folder2md --help | head -5

You should see output similar to:

folder2md4llms 0.4.x

Usage: folder2md [OPTIONS] [PATHS]...

  Convert folder structures and files into LLM-friendly Markdown.

Troubleshooting¶

Common Issues¶

Command not found¶

• Python installation: Ensure Python 3.11+ is installed
• PATH issues: Make sure the installation directory is in your PATH
• Virtual environment: If using pip, ensure your virtual environment is activated

Permission errors¶

• macOS/Linux: Use chmod +x to make binaries executable
• Windows: Use WSL2 for better compatibility (follows Linux instructions)

Import errors¶

• Dependency conflicts: Use pipx or virtual environments
• Python version: Ensure you're using Python 3.11 or later

Getting Help¶

If you encounter issues:

1. Check the version: folder2md --version
2. Review error messages: Often contain helpful debugging information
3. Search existing issues: GitHub Issues
4. Ask for help: GitHub Discussions

Next Steps¶

Once you have Folder2MD4LLMs installed:

1. Try your first conversion: First Conversion Guide
2. Learn common patterns: Quick Reference
3. Explore advanced features: User Guide

System Requirements¶

• Python: 3.11 or later (for Python installation)
• Memory: 512MB RAM minimum, 2GB recommended for large projects
• Storage: 50MB for installation, additional space for processing large projects
• Platforms: Linux (most distributions), macOS 10.14+, Windows 10+ (via WSL2)