Skip to content

Getting Started with File Organizer

This guide will help you install and set up File Organizer quickly.

Installation Methods

Choose the installation method that best fits your needs:

**Best for**: Production deployments, consistent environments

**Prerequisites**:
- Docker & Docker Compose installed
- 4GB+ available disk space

**Install**:

```bash
git clone https://github.com/curdriceaurora/Local-File-Organizer.git
cd Local-File-Organizer
cp .env.example .env
docker-compose up -d
```

**Access**: Open browser to `http://localhost:8000/ui/`

See [Deployment Guide](admin/deployment.md) for detailed Docker setup.

**Best for**: Quick testing, simple deployments

**Prerequisites**:
- Python 3.11 or higher
- Ollama installed and running
- 4GB+ available disk space

**Install**:

```bash
pip install local-file-organizer

# Start the API server
file-organizer serve
```

**Access**: Open browser to `http://localhost:8000/ui/`

See [Installation Guide](admin/installation.md) for options.

**Best for**: Users who want a native window without managing a browser tab

**Prerequisites**:
- Python 3.11 or higher
- Ollama installed and running
- Linux only: `sudo apt-get install -y libgirepository1.0-dev gir1.2-webkit2-4.1`

**Install**:

```bash
# From PyPI
pip install "local-file-organizer[desktop]"

# Or from source
git clone https://github.com/curdriceaurora/Local-File-Organizer.git
cd Local-File-Organizer
pip install -e ".[desktop]"
```

**Launch**:

```bash
ollama serve &
file-organizer-desktop
```

A native OS window opens automatically — no browser required.

See [Desktop App Guide](desktop-app.md) for installation options, configuration, and troubleshooting.

**Best for**: Development, customization

**Prerequisites**:
- Python 3.11 or higher
- Git
- Ollama installed
- Development tools (C compiler)

**Install**:

```bash
git clone https://github.com/curdriceaurora/Local-File-Organizer.git
cd Local-File-Organizer
pip install -e .

# Pull required AI models
ollama pull qwen2.5:3b-instruct-q4_K_M      # Text model
ollama pull qwen2.5vl:7b-q4_K_M             # Vision model

# Start the API server
file-organizer serve
```

**Access**: Open browser to `http://localhost:8000/ui/`

System Requirements

Minimum

  • CPU: 2-core processor
  • RAM: 8 GB
  • Storage: 10 GB (for AI models)
  • Python: 3.11+
  • Ollama: Latest version
  • CPU: 4+ cores
  • RAM: 16 GB or more
  • Storage: 20 GB SSD
  • GPU: NVIDIA, AMD, or Apple Silicon (optional, for faster processing)

Optional

  • FFmpeg: For audio/video preprocessing
  • Node.js: For plugin development
  • Docker: For containerized deployment

Optional Features

File Organizer supports modular installation through optional dependency groups. Install only the features you need:

Feature Install Command What It Enables Platform Notes
Core pip install local-file-organizer Basic file organization, Ollama integration, YAML/JSON/TXT parsing All platforms
parsers pip install local-file-organizer[parsers] PDF, Word, Excel, PowerPoint, eBook, HTML parsing All platforms
web pip install local-file-organizer[web] Web interface, REST API server, WebSocket support All platforms
cloud pip install local-file-organizer[cloud] OpenAI-compatible API providers (OpenAI, Groq, LM Studio, vLLM) Requires OPENAI_API_KEY
llama pip install local-file-organizer[llama] Direct GGUF inference via llama.cpp (no Ollama server needed) All platforms
mlx pip install local-file-organizer[mlx] Apple Silicon MLX acceleration for faster local inference macOS only
claude pip install local-file-organizer[claude] Anthropic Claude API provider (text and vision) Requires ANTHROPIC_API_KEY
audio pip install local-file-organizer[audio] Audio transcription (Faster Whisper), metadata extraction GPU recommended
video pip install local-file-organizer[video] Video frame processing, scene detection All platforms
dedup pip install local-file-organizer[dedup] Image and text similarity-based duplicate detection All platforms
archive pip install local-file-organizer[archive] 7Z and RAR archive extraction RAR requires unrar tool
scientific pip install local-file-organizer[scientific] HDF5, NetCDF, MATLAB file format support All platforms
cad pip install local-file-organizer[cad] DXF/DWG CAD file parsing All platforms
build pip install local-file-organizer[build] PyInstaller-based executable packaging All platforms
search pip install local-file-organizer[search] BM25-based search ranking algorithms All platforms
all pip install local-file-organizer[all] All optional packs above, plus development tools (pytest, mypy, ruff, etc.) and PyQt6 GUI dependencies Includes dev and gui extras in addition to feature/build packs

Example usage:

# Install multiple features at once
pip install local-file-organizer[parsers,web,cloud]

# Install from source with features
pip install -e .[parsers,web]

# Install everything
pip install local-file-organizer[all]

First Run Setup

After installation, File Organizer will guide you through initial setup:

1. Welcome Screen

When you first access File Organizer, you'll see a welcome screen with:

  • License agreement
  • Basic configuration options
  • Link to full setup guide

2. AI Model Configuration

File Organizer supports two provider modes:

Option A — Ollama (default, fully local):

  • Text Model: qwen2.5:3b-instruct-q4_K_M (~1.9 GB)
  • Vision Model: qwen2.5vl:7b-q4_K_M (~6.0 GB)

These are automatically pulled on first run if Ollama is available.

Manual pull (if needed):

ollama pull qwen2.5:3b-instruct-q4_K_M
ollama pull qwen2.5vl:7b-q4_K_M

Option B — OpenAI-compatible endpoint (cloud or local API server):

No Ollama required. Install the [cloud] extra and set environment variables:

pip install "local-file-organizer[cloud]"   # from PyPI
# pip install -e ".[cloud]"           # from source checkout

# Example: OpenAI
export FO_PROVIDER=openai
export FO_OPENAI_API_KEY=sk-...
export FO_OPENAI_MODEL=gpt-4o-mini

# Example: LM Studio (local, no key needed)
export FO_PROVIDER=openai
export FO_OPENAI_BASE_URL=http://localhost:1234/v1
export FO_OPENAI_MODEL=your-loaded-model

Option C — Anthropic Claude:

No Ollama required. Install the [claude] extra and set environment variables:

pip install "local-file-organizer[claude]"  # from PyPI
# pip install -e ".[claude]"          # from source checkout

export FO_PROVIDER=claude
export FO_CLAUDE_API_KEY=sk-ant-...
export FO_CLAUDE_MODEL=claude-3-5-sonnet-20241022

Claude supports both text and vision tasks natively — no separate vision model configuration is required (though you can override with FO_CLAUDE_VISION_MODEL).

See Configuration Guide for the full list of providers and options.

3. Workspace Configuration

Set up your workspace:

  • Workspace Path: Where to store workspace data
  • Watch Directories: Which folders to monitor (optional)
  • Organization Methodology: Choose PARA, Johnny Decimal, or Custom

4. API Configuration (Optional)

For external integrations:

  • Generate API keys
  • Configure rate limits
  • Set security options

Web Interface Overview

Once logged in, the web interface has these main sections:

Dashboard

  • Overview of recent activity
  • Quick access to main features
  • Storage statistics

File Browser

  • Browse and organize files
  • Upload new files
  • View file properties

Organization

  • Select methodology
  • Configure options
  • Start organization jobs
  • Monitor progress

Analysis

  • Duplicate detection
  • Storage analysis
  • Metadata extraction
  • Full-text search
  • Apply filters
  • Save searches
  • Export results

Settings

  • Workspace management
  • User preferences
  • API configuration

Using the CLI

File Organizer also provides a command-line interface:

Basic Commands

# Start the web server and API
file-organizer serve

# Organize files
file-organizer organize ./Downloads ./Organized

# Preview without moving (dry run)
file-organizer organize ./Downloads ./Organized --dry-run

# Preview organisation plan
file-organizer preview ./Downloads

# Search for files
file-organizer search "*.pdf" ~/Documents
file-organizer search "report" ~/Documents --type text

# Analyze a file with AI
file-organizer analyze ./report.pdf
file-organizer analyze ./report.pdf --verbose

# Auto-tag files
file-organizer autotag suggest ./Documents
file-organizer autotag popular

# Detect duplicates
file-organizer dedupe scan ./Documents

# Analyse storage
file-organizer analytics ./Documents

# View operation history
file-organizer history

# Interactive AI assistant
file-organizer copilot chat

Short Alias

Use fo instead of file-organizer:

fo serve
fo organize ./Downloads ./Organized
fo preview ./Downloads
fo search "*.pdf" ~/Documents
fo analyze ./report.pdf
fo dedupe scan ./Documents
fo analytics ./Documents

See CLI Reference for all commands.

Choosing an Organization Methodology

File Organizer supports multiple organization systems:

PARA (Projects, Areas, Resources, Archives)

Best for: Knowledge workers, complex projects

Structure:

PARA/
├── Projects/        # Active projects with deadlines
├── Areas/           # Ongoing responsibilities
├── Resources/       # Reference materials
└── Archives/        # Completed projects

Learn more: PARA Guide

Johnny Decimal

Best for: Hierarchical organization, fixed categories

Structure:

JD/
├── 10-19 Area 1/
│   ├── 11 Category A
│   ├── 12 Category B
├── 20-29 Area 2/
│   ├── 21 Category C

Learn more: Johnny Decimal Guide

Custom Methodology

Create your own organization system using rules and templates.

Learn more: Custom Methodologies

Common First Tasks

1. Upload Files

Click the Upload Files button or drag files directly into the browser.

Supported formats: 43+ file types including documents, images, videos, and more.

2. Organize Files

  1. Click Organize
  2. Select files to organize
  3. Choose methodology (PARA, Johnny Decimal, etc.)
  4. Review preview
  5. Click Apply to organize

3. Find Duplicates

  1. Click Analysis
  2. Select Duplicate Detection
  3. Choose directory to scan
  4. Review results
  5. Choose files to keep or remove

4. Search Files

  1. Click Search
  2. Enter search terms
  3. Apply filters if needed
  4. View results
  5. Export or download

5. Configure Settings

  1. Click Settings (gear icon)
  2. Update workspace preferences
  3. Generate API keys if needed
  4. Configure methodology options

Troubleshooting Installation

Ollama Connection Failed

Issue: "Cannot connect to Ollama service"

Solutions:

# Start Ollama service
ollama serve

# Verify it's running
curl http://localhost:11434/api/version

Port Already in Use

Issue: "Port 8000 is already in use"

Solution:

# Find process using port 8000
lsof -i :8000

# Use a different port when starting the server
file-organizer serve --port 8001

# Or with Docker Compose, edit .env: APP_PORT=8001

Models Not Found

Issue: "Model not found" error

Solution:

# Pull models manually
ollama pull qwen2.5:3b-instruct-q4_K_M
ollama pull qwen2.5vl:7b-q4_K_M

# Verify models are installed
ollama list

Out of Memory

Issue: "Out of memory" when processing files

Solutions:

  • Increase available RAM
  • Process smaller batches
  • Reduce maximum file size
  • Use CPU-only mode (slower but uses less RAM)

For more issues, see Troubleshooting Guide.

Next Steps

Getting Help

Ready to start? Access File Organizer at http://localhost:8000/ui/ and begin organizing your files!