v2.0.0-stable

[gtsteffaniak]

What's Changed

This version represents the most significant change to date. It requires both a database migration and config structural changes. See the migration guide for step-by-step upgrade instructions, About v2.0.0 for a full summary.

Also, consider enabling "analytics" in admin settings which will help me populate an anonymous public dashboard for everyone to see. Currently, theres 60 deployments details populated from beta, so after a percentage of you enable this in staging there should be plenty to make the dashboard useful and available. No private information is used, you can see exactly what data is sent in the UI.

Breaking Changes:

• Removed: GET /api/raw and GET /public/api/raw download routes — use /api/resources/download instead.
• Removed: /share/… URL redirect to /public/share/… — use /public/share/… directly.
• Removed: singular source search api param (use sources), bare scope paths without sourceName: prefix, and glob / useGlob aliases (use useWildcard).
• Removed config.conditionals, source-level indexingIntervalMinutes (indexing always uses adaptive scheduling), and deprecated rule fields fileNames / folderNames / top-level hidden — use config.rules with fileName, folderName, and ignoreHidden on rules. See Exclusion rules.
• Removed: deprecated userDefaults config formats (nested and flat) — use the config migration tool to convert before upgrading.
• Changed: PUT /api/users moved to the more appropriate PATCH method and requires specifying which in the body. Blank or all values are rejected.
• Changed: http related config options in server config key moved to http config key. See HTTP settings.
• Changed (reverse proxy): http.trustedHeaders (v1.5.x list) removed — use http.trustProxyHeaders: true when behind nginx, Traefik, or Caddy. When enabled, FileBrowser honors X-Forwarded-Host, X-Forwarded-Proto, X-Forwarded-For, and X-Real-IP for client IP, cookies, OIDC callbacks, WebAuthn, share URLs, rate limiting, and activity logs. Default is false (direct connection values). The config migration tool converts v1 trustedHeaders lists to trustProxyHeaders: true. See Reverse proxy and HTTP trustProxyHeaders.
• Changed: FILEBROWSER_DATABASE environment variable — use FILEBROWSER_DATABASE_PATH instead. See Environment variables and Server settings.
• Changed: Moved stream api to /api/media/stream. See API reference.
• Changed: CLI user management — canonical commands are user set <username> --password [value] and user promote <username>; set -u username,password is deprecated. See CLI reference.

Security:

• [Critical] A forged JWT could authenticate as any known belongsTo. Auth signing keys are now persisted in the application database and JWT validation fails closed when no key is configured. (GHSA-8f9r-wg7w-pfw) (Auth signing key and token migration #2987) Thanks @d3do-23 and @whoamis3c.
• [High] Restricted custom API tokens can no longer be upgraded to a full-permission session via POST /api/auth/renew (GHSA-6gr6-5qpq-888p) -- thanks @tao0845.
• [High] TOTP re-enrollment no longer allows anonymous callers to replace an existing second factor using only the account password; requires an authenticated self or admin session (GHSA-qx86-4v5r-26g5) -- thanks @tao0845.
• [Medium] Public upload shares with allowReplacements=false now reject overwrites when clients send override=true. (GHSA-3846-gh75-gp3m) Thanks @d3do-23
• [Medium] OnlyOffice callbacks verify the shared integrations.office.secret JWT and require the document key to match the cached editor session; document downloads re-validate redirect targets against the configured document-server host (SSRF); public shares with enableOnlyOffice=false reject /office/* requests server-side.
• [Low] Public share lyrics and subtitle routes honor the share's file-viewer setting, download disable flag, and download limits (GHSA-p7x3-p5jj-9xfh) -- thanks Yves Soete of Blacksight LLC. @yssoe
• Fresh installs with default admin/admin generate a random initial password and log it once (Fresh install of beta leaves well known bootstrap admin account #2977).
• OIDC login binds OAuth state to an HttpOnly cookie and rejects tampered callbacks; login/logout/session-expiry redirects reject open-redirect targets, and signup sends credentials in a JSON body instead of query parameters.
• Startup fails when the configured auth signing key differs from the persisted one; session/API token registrations record JWT expiry and expired mappings are pruned.

New Features:

• View grant mechanism to distinguish between UI viewing and download. See Access control overview.
• granular per-source file permissions (view, download, modify, create, delete) with automatic migration from global permissions
  • per-source defaults configurable in settings > access management
  • view permission is automatically set to true unless explicitly set to false. See Access control overview.
  • can be enforced for all users. See Access control overview.
• New activity logs for user activity.
  • charts and historical data
  • export to csv reports
• Media player improvements:
  • Refreshed playback queue UI: Supports thumbnails, stored into session storage, and has a "clear queue" button (Add audio visualizer, more gestures, and improve things in media player #2575) (Improve more the playback queue + metadata caching #2600).
  • Loop now has 3 states (off/single/all) and neither of them will clear the existing queue (Improve more the playback queue + metadata caching #2600).
  • New "Audio visualizer" for audio files (desktop-only), you can configure some basic things to your taste (Add audio visualizer, more gestures, and improve things in media player #2575) (Add visualizer config UI #2620).
  • The current state of the audio panel now is stored into local storage.
  • More gestures: Swipe up to enter/exit fullscreen, long-press to change playback speed, single tap to pause (Add audio visualizer, more gestures, and improve things in media player #2575).
  • Videos now will resume fullscreen and PiP when navigating (queue auto-navigation, swipes gestures or next/previous) (fix plyr popup position, placeholder and restore fullscreen and pip #2649).
• Added F4 shortcut to refresh the current directory and metadata (Improve more the playback queue + metadata caching #2600).
• opt-in feature to send deployment analytics to filebrowser quantum developer servers
  • anonymized with a viewer so users can see what info would be sent.
  • if opt-in, every month a snapshot of your deployment config would be sent to developer servers
  • this will help me know what features are being used and what versions everyone is on over time. I will also provide a public dashboard with this information in the future.
• WebDAV now supports set modification time via the X-OC-Mtime header for clients that support it (add webdav X-OC-Mtime header support #2626). See WebDAV docs.
• Copy operations now preserve their original modification times (preserve files mod time with copy operations #2642) (preserve dir modtime with copy #2647):
  • WebUI preserves both, files and directories.
  • WebDAV COPY preserves modification times only for files, is limitation we have with webdav.
• User default enhancements
  • Config userDefaults seeds SQLite on first run; only fields explicitly set in config stay locked in Settings → User defaults (other defaults remain editable)
  • Added administrator controls for universal user defaults and enforced preferences in settings > user management > user defaults.
  • Added configurable default file permissions per source in settings > access management.
  • Added a User Defaults editor for account, permission, and profile preferences in the edit/create user prompt. See User management.
• Database env var rename: FILEBROWSER_DATABASE is removed (startup fails if set). Use FILEBROWSER_DATABASE_PATH (default filebrowser.sqlite) or server.database.path in config. See Environment variables and Server settings.
• CLI: user set with --password (inline value, interactive prompt on TTY, or piped stdin); user promote for admin grant without password reset. See CLI reference.
• Require password change at next login for password-based users: new user setting requirePasswordChange (user defaults + per-user admin toggle). Bootstrap admins with a generated initial password get this automatically (#2977). Generated bootstrap passwords use a speakable word-xxxxx-xx form.
• PWA improvements for installed mobile apps: dedicated maskable icons (192/512), manifest and splash colors that follow the instance default theme, runtime theme-color sync on dark-mode toggle, and edge-to-edge safe-area layout for notched devices (Mobile and PWA styling improvements #2625) (Add PWA maskable icons and safe-area foundation for notched devices. #2869) -- thanks @APatenaude
• Users can set default view mode and thumbnail size from Profile settings (Listing options). Admins can set the same defaults for existing users and edit all profile preference defaults from the user management panel (#2884).
• Added "Upload only what's missing" to the upload conflict prompt (feat(upload): add "Upload only what's missing" to the upload conflict prompt #2985) ([Feature Request] Skip over duplicates when moving/copying files. #2553)
• Added init CLI command, which creates a minimal commented config.yaml instead of a full config (Add cli init command #2957)
• Config YAML expands $VAR and ${VAR} so values such as userPassword: "${FILEBROWSER_LDAP_USER_PASSWORD}" work (auth: methods: ldap: userPassword: "${FILEBROWSER_LDAP_USER_PASSWORD}" doesn't take the value of environment variable #3042).
• Sidebar source links can switch between aggregated usage (default) and a root-filesystem-only view via a new "Limit disk usage to source filesystem" toggle.

Notes:

• v2.x.x uses a new write-through backend state management. Changes go through a fast memory layer and also write changes to database to stay in sync. See About v2.0.0.
• CLI server start (./filebrowser), setup, version, and set rule syntax unchanged; see CLI docs
• new dropdown and input styles
• swipe gestures to dismiss notifications (re-add swipe to dismiss notifications #2672)
• user updates are more granular, don't include entire user payload.
• user.id has been moved to a backend property and all frontend apis now query users by username. Swagger has been updated. See API reference.
• removed legacy and deprecated properties from API responses and generated config output
• /api/media/stream is audio/video only (range-based chunking). Non-media inline viewing uses GET /api/resources/view. Both endpoints use the same viewToken from file metadata. See API reference.
• removed exiftool as an optional helper, always built with the supported libraries (requires 64 bit os)
• If migration issues arise, see Migration troubleshooting.
• default browser media player option removed, always uses themed plyr
• [docker] upgraded ffmpeg from 8.1.2 to 9.0
• Sidebar navigation tree rows are real hyperlinks: middle-click, Ctrl/Cmd+click, and Shift+click use the browser's default new-tab or new-window behavior.
• Pop-up preview has a 200ms debounce delay so it doesn't flash when moving the cursor across files quickly.
• Improved UI responsiveness for larger directories and Firefox, with marginal memory improvement (Firefox UI preformance is sluggish. #1773) (Big listings make Chrome crash due to memory #2879)
• Improvements to document thumbnail generation performance.
• Changed behavior for typing to select files in listing view; added more actions in advanced search (Advanced searching #2776).
• Session renew is handled by client keep-alive; per-request X-Renew-Token header handling removed.
• defaultEnabled now means the source is always added to users on startup and login.
• Webdav always shows hidden files, ignores the user preference. (WebDAV listings hide dotfiles based on user showHidden, causing sync clients to delete local hidden files #3004)
• Share download links no longer embed a token; they link to the UI, which prompts for the password before download. For direct downloads use the documented /api/share/direct API. (Direct download link is not protected by password #2888)
• Sidebar links follow source changes: renaming a source updates links, disabling/deleting a user source removes them (General Help: Renaming the source Name #2878) (Source disabled in a user's profile still shows in that user's sidebar (yellow warning, non-clickable) #2942), and adding a source via scopes auto-adds a link.
• /api/resources/download and /public/api/resources/download return HTTP 404 for missing files/directories instead of 500 (/api/resources/download returns status 500 when file is not found #2981); GET /api/resources returns 400 when path is missing or empty (GET /api/resources returns 500 when path is empty or omitted #2801).
• Added risc-v to official releases.
• A CLI password reset returns the user to a password-method user.

Bugfixes:

• Long uploads/downloads no longer lose the session mid-transfer; session keep-alive renews before expiry and auto-logout is disabled during active transfers (Disable auto logout/session expiry if there are active file transfers going #2638).
• GroupMap changes are written through to SQL so JWT/OIDC/LDAP group memberships survive restart (JWT authentication should sync groups into access-control GroupMap (like OIDC/LDAP) #2742).
• OIDC: groupsClaim is always requested and falls back to UserInfo; the verified ID-token identifier is preserved on fallback; sessions respect tokenExpirationHours (OIDC session expires despite tokenExpirationHours #3006).
• LDAP userGroups matching accepts CN-only values against full memberOf DNs and is case-insensitive (The LDAP group name in config.yaml is case-sensitive and doesn't accept only CN #3044).
• Sidebar folder links with custom names/icons/styles persist across restarts, and deleted links stay deleted (Sidebar Folder links disappear after docker restart. #2809) (Preserve deleted sidebar links across restarts #2935).
• Fixed PDF thumbnail process aborts (Process aborts (not just 500) during PDF thumbnail generation #2763), PDF preview blocking uploads (PDF preview generation prevents file uploads from completing #2752), and 401 on the PDF download button (cleanup pdf issues and small styling #2978).
• Fixed ffmpeg unresponsive lock issue (Concurrent media previews time out in FFmpeg slot acquisition #2996).
• Fixed multiple embedded subtitles with the same language (Unable to switch to the second embedded subtitle track in MKV files #2756).
• Fixed Fuji .raf thumbnail preview; unsupported image preview formats return HTTP 415 instead of 500.
• Members without download permission could not open text-based files with OnlyOffice enabled (Members without download permission receive 403 when opening text-based files despite OnlyOffice preview being enabled #2777).
• Fixed iOS 26 / WebKit multi-chunk upload stall by isolating chunk connections (Cannot upload files larger than the upload chunk size in iOS 26.6 (Build 23G71) iPad #2734).
• Mobile/UI fixes: upload options cut off (upload options get cut off on mobile #2685), uploaded image cut off (Uploading image: image gets cut-off #2765), next/previous buttons hiding on photos (Mobile UI improvements #2767), missing gallery download button (Mobile UI improvements #2767), double-tap to zoom, html viewer height, tooltips on mobile, assorted styling inconsistencies (Fix more styles #2908).
• Public share folder and multi-file ZIP downloads were empty for anonymous visitors on sources with deny-by-default/path rules (Empty Zip files downloaded unless authenticated #2631) (Downloading as zip or tar.gz creating corrupted archive #2365).
• Preserve Ctrl-click selection with stale keyboard state (fix: preserve Ctrl-click file selection when keyboard state is stale #2958) (Previously selected files or folders become deselected when multi-selecting in FileBrowser #2923); avoid false stalls in parallel transfers (fix(upload): avoid false stalls during parallel transfers #2950) (Hardcoded 10s stall timeout causes false-positive pauses with many parallel uploads #2948) thanks @gudcks0305; hide Replace on conflict prompts when the user lacks modify permission (Create without Edit or Delete permission allows "creating" existing files, effectively editing/deleting #2837).
• Disk usage: fixed overstatement on virtiofs/Docker Desktop (Disk usage widget shows PB/TB-scale garbage on Docker Desktop for Mac (virtiofs) bind mounts #2894), inflated usage across ZFS datasets/btrfs subvolumes (Source total capacity multiplied by number of ZFS child datasets (v2.0.9-beta, regression from #2761) #3025) (Incorrect (>100%) disk usage reported when source spans multiple ZFS datasets #2997), capped usage bars at 100% and summed nested mounts on Linux (Usage bar shows >100% (e.g. 1294%) when source root contains a larger mounted sub-filesystem #2761) (partition/disk reporting #2238).
• Support non-ASCII share passwords (Support non-ASCII share passwords #2933); fall back to buffered copies when FUSE rejects fast paths (Fall back to buffered copies when FUSE rejects fast paths #2938) (Copying files or directories between two rclone FUSE mounts fails #2924); tilde (~) source paths expand properly.
• Fixed slow/broken file listing when http.baseURL is a subpath.
• SQLite: removed shared cache and set busy_timeout on every pooled connection; busy errors no longer reported as success or empty cache results.

Full Changelog: v1.5.8-stable...v2.0.0-stable

---

This discussion was created from the release v2.0.0-stable.

[caddish]

Migration went almost perfectly but somehow the OIDC redirect_uri switched from https to http

"The redirect_uri 'http://file.mydomain.com/api/auth/oidc/callback' is not registered for this client."

Where can I fix that ?

[gtsteffaniak]

Likely because you need to enable trusteProxyHeaders -- you like also see this warning on startup?

logger.Warning("OIDC is enabled but http.trustProxyHeaders is false. Behind a reverse proxy, FileBrowser builds the OIDC redirect_uri from the incoming request; set trustProxyHeaders: true and configure your proxy to send X-Forwarded-Proto and X-Forwarded-Host. http.externalUrl does not apply to OIDC redirects.")

This is assuming you access your site from a real https domain like https://file.mydomain.com instead of http

[gtsteffaniak]

see https://filebrowserquantum.com/en/docs/getting-started/reverse-proxy/

[hraphael]

The migration went fine but the previews seem to be broken. When hovering overr a folder a popup comes with "Popup image" and the broken image and in the log there is a error 500 "/api/resources/preview?path=%2FXXXXXXXX%2F&key=1786905624624&source=XXXXXXXX&inline=true&size=xlarge&atPercentage=25" with "this item does not have a preview" but in the info hasPreview is true.
The thumbnails from video files are just gone.

[gtsteffaniak]

please do a hard refresh to clear cache on your browser.

[hraphael]

I have opend it on a different browser and when I scroll on the page it spams the log with for every folder:
21:49:07 GET | 500 | 192.168.0.226 | admin | 83ms | "/api/resources/preview?path=XXXXXXXXX&key=1790274264699&source=XXXXXXXX&inline=true"

Do the preview images regennerate over time or is there a button to force it for a source/folder?

[gtsteffaniak]

Hmm, try stopping your service, clearing your cache dir and reloading. if that fixes it, I might have to update the docs to mention that, I haven't heard anyone else complain about that

[hraphael]

That solved the spam in the log

[Libraaaaa2792]

I'm unable to sign in with OIDC anymore. Authentik: "Redirect URI Error".

[Libraaaaa2792]

Adding the following to config file fixed it:
http: trustProxyHeaders: true

[gtsteffaniak]

I've updated the migration docs to call that out more clearly!