Home›Guides
Stash Beginner Setup: How to Get Your Library Scanning and Tagging
Stash is the most capable free tool for organising a downloaded adult video collection — but it is not a simple download-and-run app. It runs as a local server you open in a browser, requires command-line setup even with the native binary, and needs scraper configuration plus ongoing maintenance. This guide walks through each step honestly, aligned with Stash's current StashDB and Scene Tagger workflow.
Before You Start: Is Stash Right for You?
Stash excels at metadata — performer pages, studio filters, tags, and cover art pulled automatically for large libraries. It is weaker at everything that happens after you find a scene: multi-video grids, hands-free session automation, and file-level encryption are all outside what Stash was built to do.
Stash is the right choice if:
- You have thousands of videos and want deep performer and studio metadata
- You want browsable performer pages with bios and scene counts
- You download studio-produced content that StashDB can match reliably
- You are comfortable running a local server from the command line
- You want library access from other devices on your home network
Consider an alternative if:
- You want a native desktop player with no browser UI and no server setup
- Command-line install and ongoing scraper maintenance feel like too much overhead
- You need multi-stream playback, a Swap Timer, or AES-256 encryption
- Most of your files have camera-style names scrapers will never match
- You mainly want to watch sessions, not catalogue metadata for its own sake
Step-by-Step Setup
This path matches what Stash users follow in 2026: native binary or Docker install, library scan, pHash generation, StashDB matching through the Scene Tagger, then community scrapers for anything left unmatched.
Download Stash (native binary or Docker)
Stash provides native binaries for Mac, Windows, and Linux on stashapp.cc — Docker is optional, not required. Most beginners should start with the native binary: download it for your OS, place it somewhere permanent, and run it from Terminal (Mac/Linux) or PowerShell/CMD (Windows). Docker is an alternative if you already use containers or want to run Stash on a NAS — see the official Stash wiki for the current Docker run command and volume mappings.
↳ Stash is a local server, not a desktop app with its own window. You manage it through a browser at localhost:9999 after it starts.
Start Stash and open the web UI
Launch Stash from the command line. On first run, Stash listens on port 9999 by default. Open http://localhost:9999 in any browser on the same machine. The Setup Wizard walks you through basic configuration — set a username/password if you want UI login, then move on to library paths.
↳ If the page won't load, Stash isn't running or something else is using port 9999. Check the terminal output for errors.
Add library folders and run your first scan
Go to Settings → Library and add the folder(s) where your downloaded videos live. Stash does not move or rename your files — it indexes them in place and builds its own database alongside them. Then go to Tasks → Scan and run a full library scan. Stash generates thumbnails and indexes every video. A few thousand files often takes 10–30 minutes; very large libraries can take hours on first scan.
↳ Let the first scan finish before tagging. Interrupting mid-scan usually means running it again from the start.
Enable perceptual hash (pHash) generation
Before StashDB matching will work, Stash needs perceptual hashes for your files. Go to Settings → Tasks and enable “Generate perceptual hashes” under both the Library/Scan section and the Generate section. Run a Generate task after your scan completes. Without pHashes, automatic scene matching against StashDB will not work.
↳ This step is easy to skip and then wonder why tagging finds nothing. Do it once before opening the Scene Tagger.
Run the Scene Tagger against StashDB
Go to your Scenes page and open the Scene Tagger (bookmark icon). Click Scrape All. Stash matches each video's pHash against StashDB — the community metadata database — and returns performer names, studio, scene title, tags, and cover art for matched scenes. Review results and save. For studio-produced content with standard filenames, match rates are typically strong; amateur, re-encoded, or oddly named files often need manual work.
↳ StashDB is the primary path for metadata. Community site scrapers are the fallback for content not in the database — not the first step.
Install community scrapers for unmatched content
For scenes StashDB did not match, install scrapers from Settings → Metadata Providers (Community feed). These small scripts pull metadata from adult site pages when you point Stash at a URL. Useful for content outside StashDB, but they require more manual maintenance when sites change.
↳ Scraper quality varies by site. Budget time to update plugins when scrapers break — the Stash Discord and r/stashapp are the fastest places to get help.
Maintain and update
Stash needs ongoing care: re-scan when you add new downloads, regenerate hashes for new files, re-run the Scene Tagger periodically, and update Stash when new releases ship. Native binary users download the new release and restart; Docker users pull the new image and recreate the container with the same volume mappings so the database persists.
↳ Your database and generated thumbnails live in Stash's config/data folders — back them up before major upgrades.
Common Setup Issues (and Fixes)
Problem: Can't access localhost:9999 in browser
Fix: Confirm Stash is still running in the terminal window that launched it. Native binary: restart the executable. Docker: run docker ps and verify the container is up; if stopped, docker start or re-run your docker run command with the same volume mappings.
Problem: Scan runs but finds 0 videos
Fix: The library path in Settings → Library does not point at the folder that actually contains your video files. Add the parent folder where the files live, save, and scan again.
Problem: Scene Tagger / StashDB finds no matches
Fix: pHashes probably were not generated — go back to step 04. Also check filename and content type: studio releases in StashDB match far more reliably than camera footage or heavily re-encoded files.
Problem: Stash stops running after reboot
Fix: Native binary: you need to start Stash again manually or add it to your OS startup scripts. Docker: add --restart unless-stopped to your docker run command, or enable restart policy in Docker Desktop.
Problem: Stash update broke my setup
Fix: Native binary: download the new release and replace the executable — your config folder persists separately. Docker: pull the new image, stop/remove the old container, recreate with identical volume mappings. Your database lives in the mapped folders, not inside the container.
What Stash Doesn't Do (and What to Pair With It)
A working Stash install still leaves three gaps for many collectors: no multi-video grid, no file-level encryption, and no hands-free session automation. Stash organises and plays one scene at a time through a browser — that is by design, not a missing feature waiting for an update.
Gap: Multi-video sessions
VidVana — 2×2 to 5×5 grid with Swap Timer and Weighted Favorites
Gap: Library encryption
VidVana — AES-256 on library index data, Duress PIN, Panic Hide
Gap: Session automation
VidVana — hands-free tile rotation, tile pinning, Quick Play presets
Many serious collectors run both: Stash for scraping and cataloguing, VidVana Pro for session playback. VidVana Pro reads your Stash database file in read-only mode — performers, studios, tags, and scene markers sync into VidVana without re-tagging. Stash does not need to stay running for that sync to work after the first import.
More Guides
Stash is free and open-source at stashapp.cc. Refer to Stash's official documentation for the latest install commands and release notes.