Stash: Self-Hosted Media Organizer for Video Collections

A Self-Hosted Organizer for Local Media Collections

Stash addresses a specific gap: organizing large personal video and image libraries without sending data to a third-party service. The application is written in Go and presents a web-based interface that a user accesses through a browser. The README describes it as catering to both SFW and NSFW content. Where a general-purpose media server like Plex or Jellyfin indexes movies and TV shows by matching titles against public databases, Stash is oriented around performer, studio, and scene metadata specific to adult content, including crowd-sourced databases not covered by mainstream metadata providers.

The target user is someone with an existing local collection who wants tags, performer profiles, studio associations, and scene descriptions without manual data entry for every file. The application does not host or distribute content; it reads from directories the user specifies.

How Stash Scans and Identifies Your Files

The indexing process starts with a Scan, which Stash runs against the media directories configured during first setup. Scanning catalogues files into Stash's SQLite database. After scanning, the user runs identification tasks to attach metadata.

Metadata can come from three sources. StashDB, the canonical instance of the open-source stash-box API, is a crowd-sourced repository of scene, studio, and performer information focused on mainstream digital releases. It requires an invite code to access. Several community-operated stash-box instances cover different niches and have their own sign-up processes. Finally, community-maintained scrapers can pull data from individual websites; these are available from Settings, under Metadata Providers, then Available Scrapers, then Community (stable). The README notes that scrapers are trickier to use than a stash-box connection because each one behaves differently.

On the technology side, the backend uses chromedp (a Chrome DevTools Protocol library) for scraping tasks that require a real browser, and goja (a JavaScript runtime) to execute scraper scripts. The HTTP server is go-chi/chi, and configuration is managed through koanf. All of this is compiled as a single CGO binary due to the sqlite3 dependency.

Installing Stash and Running Your First Scan

Stash provides pre-built binaries for Windows, macOS, Linux, and multiple Linux architectures. The releases page also offers nightly development builds. On Linux, the process is:

chmod +x stash-linux
./stash-linux

On macOS, the application ships as a signed app bundle in a zip archive. As of v0.29.0, macOS 11 Big Sur or later is required; as of v0.32.0 the minimum is macOS 12 Monterey. Windows requires Windows 10 or Server 2016 at minimum, a requirement introduced in v0.27.0.

FFmpeg is a hard dependency. If it is not present on the system, Stash will prompt the user to download a copy during the initial setup wizard. On Linux, the README recommends installing FFmpeg from the distribution's package manager rather than using the bundled download.

Once running, the interface is available at http://localhost:9999 by default. On first launch, Stash asks for media directories to index, then runs the initial scan. The in-app manual is available at any time by pressing Shift and ? together.

For Docker deployments, the repository provides a sample docker-compose.yml file under the docker/production/ directory and a Docker Hub image at stashapp/stash.

Connecting Metadata Sources and Using Scrapers

Identifying an entire collection through automated means requires connecting at least one metadata source. The typical starting point is StashDB, for which the user needs an invite code; the documentation covers how to obtain one through the community forum or Discord. Once a stash-box instance is connected, Stash can match scene fingerprints against the database and populate performer, studio, and tag data automatically.

For content not covered by stash-box instances, community scrapers fill the gap. They are managed directly inside the application. Under Settings, then Metadata Providers, then Available Scrapers, the Community (stable) list shows scrapers that can be installed with a single click and updated from within the same panel.

The stash-box protocol itself is open source (the stash-box repository is linked from the README), so operators can also run their own private instance if they need to share metadata within a closed group without connecting to any public database.

Where Stash Requires Manual Effort

Stash does not guess at metadata. If a file does not match anything in the connected stash-box instances and no scraper covers the source site, the scene stays unidentified until the user fills in fields by hand. This is a real limitation for collections of rare or niche content from sites without community scraper support.

The AGPL-3.0 license requires that any modified version of Stash that is offered over a network must be distributed with its source code. This affects anyone building a hosted service on top of Stash rather than running it privately.

The Go binary requires CGO, which means cross-compilation is more involved than for a pure Go binary. The build requires sqlite_stat4 and sqlite_math_functions build tags, as shown in the Makefile. Users compiling from source on unusual targets need a working C toolchain.

Stash also does not transcode on the fly for remote playback in the way that Plex or Jellyfin do. Its primary design assumes the client has access to the same network as the server and can play the source format directly.

Stash versus General-Purpose Media Servers

Plex and Jellyfin are the obvious alternatives for media organization. Both match content against public movie and television databases such as TheMovieDB and TheTVDB, which do not index adult content. Jellyfin is LGPL-2.1 and fully self-hosted; Plex offers a free server but monetizes through a subscription for remote access features.

Stash takes the opposite approach to metadata discovery. Instead of matching filenames against a general database, it uses scene fingerprints (file hashes) to match against specialized crowd-sourced databases. This produces accurate metadata when the file is in the database, and nothing when it is not. Plex and Jellyfin use filename parsing, which produces plausible-looking but often incorrect results for content with non-standard naming.

For a collection of mainstream adult digital releases, Stash with StashDB will typically outperform any general-purpose server. For a mixed collection that includes standard films and television, the two categories need separate tools.

Technology Stack, License, and Maintenance

Stash is licensed under the GNU Affero General Public License version 3. The source is on GitHub under the stashapp organization. The latest stable release is v0.31.1 (published 2026-04-13), with ongoing development builds tracking the develop branch; the last push to the repository was on 2026-09-22.

The backend is pure Go with gqlgen providing the GraphQL API layer, go-chi/chi as the HTTP router, and mattn/go-sqlite3 for persistent storage. The frontend is a React application. Build requires Make, Node, and a Go version meeting the go.mod minimum (currently 1.25). The Makefile documents the full release process: pre-ui, generate, ui, and build-release must be run in order.

Plugins are documented at docs.stashapp.cc/plugins, and community-developed plugins can extend behavior beyond what the core application provides. The community maintains a forum at discourse.stashapp.cc and a Discord server, both linked from the README.

Editorial conclusion

Stash is the right choice for someone who wants to run their own metadata-enriched media library on hardware they control, and who is willing to configure scraper connections manually. It is not the right choice for users who need a ready-to-run cloud service, or who are on Windows 7 or 8. Before deploying, verify that FFmpeg is available on the target system and that at least one of StashDB or a community stash-box instance is accessible, since Stash without a connected metadata source requires entirely manual tagging.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. stashapp/stash on GitHub