Published: October 8, 2025
Last updated: July 24, 2026
Suggest an edit

Configure server-side behavior: database, caching, indexing, previews, sources, and logging. For port, baseURL, TLS, and reverse-proxy options, see HTTP settings.

Basic Server Configuration

YAML 
1
2
3
4
5
6

server:
  database:
    path: "filebrowser.sqlite"
  cacheDir: "tmp"
  sources:
    - path: "/srv"

Configuration Options

minSearchLength

Minimum length of search query to begin searching (default: 3)

YAML 
1
2

server:
  minSearchLength: 3

disableUpdateCheck

Disable backend update check service

YAML 
1
2

server:
  disableUpdateCheck: false

numImageProcessors

Number of concurrent image processing jobs used to create previews. Default is number of CPU cores available.

YAML 
1
2

server:
  numImageProcessors: 4

disablePreviews

Disable all previews and thumbnails. Simple icons will be used instead.

YAML 
1
2

server:
  disablePreviews: false

disablePreviewResize

Disable resizing of previews for faster loading over slow connections.

YAML 
1
2

server:
  disablePreviewResize: false

disableTypeDetectionByHeader

Disable type detection by header. Useful if filesystem is slow.

YAML 
1
2

server:
  disableTypeDetectionByHeader: false

cacheDirCleanup

Whether to automatically cleanup the cache directory. Note: Docker must also mount a persistent volume to persist the cache (default: false).

YAML 
1
2

server:
  cacheDirCleanup: false

filesystem

Filesystem settings for file and directory creation permissions.

YAML 
1
2
3
4

server:
  filesystem:
    createFilePermission: "644"      # Unix permissions like 644, 755, 2755 (default: 644)
    createDirectoryPermission: "755" # Unix permissions like 755, 2755, 1777 (default: 755)

indexSqlConfig

Index database SQL configuration for performance tuning.

YAML 
1
2
3
4
5
6
7

server:
  indexSqlConfig:
    batchSize: 1000           # Number of items to batch in a single transaction, typically 500-5000. Higher = faster but could use more memory.
    cacheSizeMB: 32         # Size of the SQLite cache in MB
    walMode: false          # WAL journaling mode: more memory, better for busy deployments
    disableReuse: false       # If true, always create a new indexing database on startup
    startupIntegrityCheck: quickCheck  # quickCheck | probe | off — how thoroughly to verify the index DB at startup (default: quickCheck)

startupIntegrityCheck (default: quickCheck):

If you notice long delays on startup, you could configure this to probe (recommended) or off to reduce the startup check time.

  • quickCheck — Runs SQLite PRAGMA quick_check. Thorougher on very large databases.
  • probe — Lightweight check (catalog / sample read); faster for huge indexes.
  • off — Minimal check beyond opening the DB; fastest boot, least safety.

sources

Configure file system sources. See Sources configuration for detailed information.

logging

Configure logging output and levels. See Logging configuration for detailed information.

database

SQLite database file path. See database path priority for defaults and env var overrides.

YAML 
1
2
3
4

server:
  database:
    path: "data/filebrowser.sqlite"
    migrateFrom: "database.db.old"  # one-time v1 → v2 migration only

Default locations (v2.0.0+):

  • Standalone: ./filebrowser.sqlite
  • Docker (with ./data mount): /home/filebrowser/data/filebrowser.sqlite

During upgrade from v1.x, set migrateFrom to your renamed BoltDB file. Remove it after migration — see v2 migration guide.

Storage quotas (v2.1.0+) (folder, per-user scope, and share caps) use additional SQLite tables added in v2.1.0. They are created automatically on upgrade; legacy Bolt imports do not carry over quota limits. See Storage quotas (v2.1.0+).

Optional quota counter flush tuning (v2.1.0+):

YAML 
1
2
3
4
5
6

server:
  database:
    path: "data/filebrowser.sqlite"
    quotas:
      flushIntervalSeconds: 10   # batch write interval for tracked usage counters (default 10)
      flushMaxBuffers: 500       # flush when this many dirty counters are queued (default 500)

maxArchiveSize

FileBrowser limits the maximum size of archive and unarchive operations (folder downloads, ZIP handling, etc.). The limit is the combined size of files involved, in gigabytes. Default is 20 GB. Set to 0 for no limit.

This cap exists because archiving uses temporary files under cacheDir and an unlimited value could exhaust disk or memory on the server.

Ensure you have enough free space in cacheDir if you raise this value.

YAML 
1
2

server:
  maxArchiveSize: 20   # GB; 0 = no limit (default: 20)

cacheDir

The cacheDir is a critical configuration that defines where FileBrowser stores temporary files during various operations. By default, a tmp folder is created in the same directory as the program is run, but this may not be ideal. For example unRAID uses a different user by default and that causes permission issues with the default cache directory creation process.

Important Considerations

The cacheDir is used by:

  • Image preview generation: Thumbnails and processed images are cached
  • Archive operations: ZIP extraction and compression temporary files
  • Document processing: Temporary files during PDF/image conversion
  • Video processing: Some media files during video operations
YAML 
1
2

server:
  cacheDir: "tmp" # this is default when not configured.

Docker Examples

Basic Docker Setup:

YAML 
1
2
3
4
5
6
7
8
9

# docker-compose.yaml
services:
  filebrowser:
    image: gtstef/filebrowser:stable
    volumes:
      - '/path/to/your/data:/srv'
      - '/var/cache/filebrowser:/tmp/filebrowser'  # Mount cache directory
    environment:
      FILEBROWSER_CONFIG: "/config/config.yaml"

Corresponding config.yaml:

YAML 
1
2

server:
  cacheDir: /tmp/filebrowser # corrosponds to above

Troubleshooting

Permission Issues:

By default, FileBrowser uses UID 1000 for the user (you can change that):

BASH 
1
2

# Fix permissions for cache directory
sudo chown -R 1000:1000 /var/cache/filebrowser

Next Steps