Windows | 
macOS | 
Linux | 
Docker
:---:|:---:|:---:|:---:
[Latest Release](https://github.com/stashapp/stash/releases/latest/download/stash-win.exe) [Development Preview](https://github.com/stashapp/stash/releases/download/latest_develop/stash-win.exe) | [Latest Release](https://github.com/stashapp/stash/releases/latest/download/Stash.app.zip)
[Development Preview](https://github.com/stashapp/stash/releases/download/latest_develop/Stash.app.zip) | [Latest Release (amd64)](https://github.com/stashapp/stash/releases/latest/download/stash-linux)
[Development Preview (amd64)](https://github.com/stashapp/stash/releases/download/latest_develop/stash-linux)
[More Architectures...](https://github.com/stashapp/stash/releases/latest) | [Instructions](docker/production/README.md)
[Sample docker-compose.yml](docker/production/docker-compose.yml) Download links for other platforms and architectures are available on the [Releases](https://github.com/stashapp/stash/releases) page. ## First Run #### Windows/macOS Users: Security Prompt On Windows or macOS, running the app might present a security prompt since the application binary isn't yet signed. - On Windows, bypass this by clicking "more info" and then the "run anyway" button. - On macOS, Control+Click the app, click "Open", and then "Open" again. #### ffmpeg Stash requires FFmpeg. If you don't have it installed, Stash will prompt you to download a copy during setup. It is recommended that Linux users install `ffmpeg` from their distro's package manager. # Usage ## Quickstart Guide Stash is a web-based application. Once the application is running, the interface is available (by default) from `http://localhost:9999`. On first run, Stash will prompt you for some configuration options and media directories to index, called "Scanning" in Stash. After scanning, your media will be available for browsing, curating, editing, and tagging. Stash can pull metadata (performers, tags, descriptions, studios, and more) directly from many sites through the use of [scrapers](https://github.com/stashapp/stash/blob/develop/ui/v2.5/src/docs/en/Manual/Scraping.md), which integrate directly into Stash. Identifying an entire collection will typically require a mix of multiple sources: - The stashapp team maintains [StashDB](https://stashdb.org/), a crowd-sourced repository of scene, studio, and performer information. Connecting it to Stash will allow you to automatically identify much of a typical media collection. It runs on our stash-box software and is primarily focused on mainstream digital scenes and studios. Instructions, invite codes, and more can be found in this guide to [Accessing StashDB](https://guidelines.stashdb.org/docs/faq_getting-started/stashdb/accessing-stashdb/). - Several community-managed stash-box databases can also be connected to Stash in a similar manner. Each one serves a slightly different niche and follows their own methodology. A rundown of each stash-box, their differences, and the information you need to sign up can be found in this guide to [Accessing Stash-Boxes](https://guidelines.stashdb.org/docs/faq_getting-started/stashdb/accessing-stash-boxes/). - Many community-maintained scrapers can also be downloaded, installed, and updated from within Stash, allowing you to pull data from a wide range of other websites and databases. They can be found by navigating to `Settings → Metadata Providers → Available Scrapers → Community (stable)`. These can be trickier to use than a stash-box because every scraper works a little differently. For more information, please visit the [CommunityScrapers repository](https://github.com/stashapp/CommunityScrapers). - All of the above methods of scraping data into Stash are also covered in more detail in our [Guide to Scraping](https://docs.stashapp.cc/beginner-guides/guide-to-scraping/). [StashDB](http://stashdb.org) is the canonical instance of our open source metadata API, [stash-box](https://github.com/stashapp/stash-box). # Translation [](https://translate.codeberg.org/engage/stash/) Stash is available in 32 languages (so far!) and it could be in your language too. We use Weblate to coordinate community translations. If you want to help us translate Stash, you can make an account at [Codeberg's Weblate](https://translate.codeberg.org/projects/stash/stash/) to contribute to new or existing languages. Thanks! The badge below shows the current translation status of Stash across all supported languages: [](https://translate.codeberg.org/engage/stash/) # Support & Resources Need help or want to get involved? Start with the documentation, then reach out to the community if you need further assistance. - Documentation - Official docs: https://docs.stashapp.cc - official guides guides and troubleshooting. - In-app manual: press Shift + ? in the app or view the manual online: https://docs.stashapp.cc/in-app-manual. - FAQ: https://discourse.stashapp.cc/c/support/faq/28 - common questions and answers. - Community wiki: https://discourse.stashapp.cc/tags/c/community-wiki/22/stash - guides, how-to’s and tips. - Community & discussion - Community forum: https://discourse.stashapp.cc - community support, feature requests and discussions. - Discord: https://discord.gg/2TsNFKt - real-time chat and community support. - GitHub discussions: https://github.com/stashapp/stash/discussions - community support and feature discussions. - Lemmy community: https://discuss.online/c/stashapp - Reddit-style community space. - Community scrapers & plugins - Metadata sources: https://docs.stashapp.cc/metadata-sources/ - Plugins: https://docs.stashapp.cc/plugins/ - Themes: https://docs.stashapp.cc/themes/ - Other projects: https://docs.stashapp.cc/other-projects/ # For Developers Pull requests are welcome! See [Development](docs/DEVELOPMENT.md) and [Contributing](docs/CONTRIBUTING.md) for information on working with the codebase, getting a local development setup, and contributing changes. ================================================ FILE: cmd/phasher/main.go ================================================ // TODO: document in README.md package main import ( "fmt" "os" "os/exec" "path/filepath" flag "github.com/spf13/pflag" "github.com/stashapp/stash/pkg/ffmpeg" "github.com/stashapp/stash/pkg/hash/imagephash" "github.com/stashapp/stash/pkg/hash/videophash" "github.com/stashapp/stash/pkg/models" ) func customUsage() { fmt.Fprintf(os.Stderr, "Usage:\n") fmt.Fprintf(os.Stderr, "%s [OPTIONS] FILE...\n\nOptions:\n", os.Args[0]) flag.PrintDefaults() } func printPhash(ff *ffmpeg.FFMpeg, ffp *ffmpeg.FFProbe, inputfile string, quiet *bool) error { // Determine if this is a video or image file based on extension ext := filepath.Ext(inputfile) ext = ext[1:] // remove the leading dot // Common image extensions imageExts := map[string]bool{ "jpg": true, "jpeg": true, "png": true, "gif": true, "webp": true, "bmp": true, "avif": true, } if imageExts[ext] { return printImagePhash(ff, inputfile, quiet) } return printVideoPhash(ff, ffp, inputfile, quiet) } func printVideoPhash(ff *ffmpeg.FFMpeg, ffp *ffmpeg.FFProbe, inputfile string, quiet *bool) error { ffvideoFile, err := ffp.NewVideoFile(inputfile) if err != nil { return err } // All we need for videophash.Generate() is // videoFile.Path (from BaseFile) // videoFile.Duration // The rest of the struct isn't needed. vf := &models.VideoFile{ BaseFile: &models.BaseFile{Path: inputfile}, Duration: ffvideoFile.FileDuration, } phash, err := videophash.Generate(ff, vf) if err != nil { return err } if *quiet { fmt.Printf("%x\n", *phash) } else { fmt.Printf("%x %v\n", *phash, vf.Path) } return nil } func printImagePhash(ff *ffmpeg.FFMpeg, inputfile string, quiet *bool) error { imgFile := &models.ImageFile{ BaseFile: &models.BaseFile{Path: inputfile}, } phash, err := imagephash.Generate(ff, imgFile) if err != nil { return err } if *quiet { fmt.Printf("%x\n", *phash) } else { fmt.Printf("%x %v\n", *phash, imgFile.Path) } return nil } func getPaths() (string, string) { ffmpegPath, _ := exec.LookPath("ffmpeg") ffprobePath, _ := exec.LookPath("ffprobe") return ffmpegPath, ffprobePath } func main() { flag.Usage = customUsage quiet := flag.BoolP("quiet", "q", false, "print only the phash") help := flag.BoolP("help", "h", false, "print this help output") flag.Parse() if *help { flag.Usage() os.Exit(2) } args := flag.Args() if len(args) < 1 { fmt.Fprintf(os.Stderr, "Missing FILE argument.\n") flag.Usage() os.Exit(2) } if len(args) > 1 { fmt.Fprintln(os.Stderr, "Files will be processed sequentially! If required, use e.g. GNU Parallel to run concurrently.") fmt.Fprintf(os.Stderr, "Example: parallel %v ::: *.mp4\n", os.Args[0]) } ffmpegPath, ffprobePath := getPaths() encoder := ffmpeg.NewEncoder(ffmpegPath) // don't need to InitHWSupport, phashing doesn't use hw acceleration ffprobe := ffmpeg.NewFFProbe(ffprobePath) for _, item := range args { if err := printPhash(encoder, ffprobe, item, quiet); err != nil { fmt.Fprintln(os.Stderr, err) } } } ================================================ FILE: cmd/stash/main.go ================================================ //go:generate go run github.com/99designs/gqlgen package main import ( "errors" "fmt" "net/http" "os" "os/signal" "runtime/debug" "runtime/pprof" "syscall" "github.com/spf13/pflag" "github.com/stashapp/stash/internal/api" "github.com/stashapp/stash/internal/build" "github.com/stashapp/stash/internal/desktop" "github.com/stashapp/stash/internal/log" "github.com/stashapp/stash/internal/manager" "github.com/stashapp/stash/internal/manager/config" "github.com/stashapp/stash/pkg/logger" "github.com/stashapp/stash/ui" _ "github.com/golang-migrate/migrate/v4/database/sqlite3" _ "github.com/golang-migrate/migrate/v4/source/file" ) var exitCode = 0 func main() { defer func() { if exitCode != 0 { os.Exit(exitCode) } }() defer recoverPanic() initLogTemp() helpFlag := false pflag.BoolVarP(&helpFlag, "help", "h", false, "show this help text and exit") versionFlag := false pflag.BoolVarP(&versionFlag, "version", "v", false, "show version number and exit") cpuProfilePath := "" pflag.StringVar(&cpuProfilePath, "cpuprofile", "", "write cpu profile to file") pflag.Parse() if helpFlag { pflag.Usage() return } if versionFlag { fmt.Println(build.VersionString()) return } cfg, err := config.Initialize() if err != nil { exitError(fmt.Errorf("config initialization error: %w", err)) return } l := initLog(cfg) if cpuProfilePath != "" { if err := initProfiling(cpuProfilePath); err != nil { exitError(err) return } defer pprof.StopCPUProfile() } // initialise desktop.IsDesktop here so that it doesn't get affected by // ffmpeg hardware checks later on desktop.InitIsDesktop() mgr, err := manager.Initialize(cfg, l) if err != nil { exitError(fmt.Errorf("manager initialization error: %w", err)) return } defer mgr.Shutdown() server, err := api.Initialize() if err != nil { exitError(fmt.Errorf("api initialization error: %w", err)) return } defer server.Shutdown() exit := make(chan int) go func() { err := server.Start() if !errors.Is(err, http.ErrServerClosed) { exitError(fmt.Errorf("http server error: %w", err)) exit <- 1 } }() go handleSignals(exit) desktop.Start(exit, &ui.FaviconProvider) exitCode = <-exit } // initLogTemp initializes a temporary logger for use before the config is loaded. // Logs only error level message to stderr. func initLogTemp() *log.Logger { l := log.NewLogger() l.Init("", true, "Error", 0) logger.Logger = l return l } func initLog(cfg *config.Config) *log.Logger { l := log.NewLogger() l.Init(cfg.GetLogFile(), cfg.GetLogOut(), cfg.GetLogLevel(), cfg.GetLogFileMaxSize()) logger.Logger = l return l } func initProfiling(path string) error { f, err := os.Create(path) if err != nil { return fmt.Errorf("unable to create CPU profile file: %v", err) } if err = pprof.StartCPUProfile(f); err != nil { return fmt.Errorf("could not start CPU profiling: %v", err) } logger.Infof("profiling to %s", path) return nil } func recoverPanic() { if err := recover(); err != nil { exitCode = 1 logger.Errorf("panic: %v\n%s", err, debug.Stack()) if desktop.IsDesktop() { desktop.FatalError(fmt.Errorf("Panic: %v", err)) } } } func exitError(err error) { exitCode = 1 logger.Error(err) // #5784 - log to stdout as well as the logger // this does mean that it will log twice if the logger is set to stdout fmt.Println(err) if desktop.IsDesktop() { desktop.FatalError(err) } } func handleSignals(exit chan<- int) { // handle signals signals := make(chan os.Signal, 1) signal.Notify(signals, syscall.SIGINT, syscall.SIGTERM) <-signals exit <- 0 } ================================================ FILE: cmd/stash/main_test.go ================================================ package main import "testing" func TestStub(t *testing.T) { } ================================================ FILE: docker/build/x86_64/Dockerfile ================================================ # This dockerfile should be built with `make docker-build` from the stash root. # Build Frontend FROM node:24-alpine AS frontend RUN apk add --no-cache make git ## cache node_modules separately COPY ./ui/v2.5/package.json ./ui/v2.5/pnpm-lock.yaml /stash/ui/v2.5/ WORKDIR /stash COPY Makefile /stash/ COPY ./graphql /stash/graphql/ COPY ./ui /stash/ui/ # pnpm install with npm RUN npm install -g pnpm RUN make pre-ui RUN make generate-ui ARG GITHASH ARG STASH_VERSION RUN BUILD_DATE=$(date +"%Y-%m-%d %H:%M:%S") make ui-only # Build Backend FROM golang:1.24.3-alpine AS backend RUN apk add --no-cache make alpine-sdk WORKDIR /stash COPY ./go* ./*.go Makefile gqlgen.yml .gqlgenc.yml /stash/ COPY ./graphql /stash/graphql/ COPY ./scripts /stash/scripts/ COPY ./pkg /stash/pkg/ COPY ./cmd /stash/cmd/ COPY ./internal /stash/internal/ # needed for generate-login-locale COPY ./ui /stash/ui/ RUN make generate-backend generate-login-locale COPY --from=frontend /stash /stash/ ARG GITHASH ARG STASH_VERSION RUN make flags-release flags-pie stash # Final Runnable Image FROM alpine:latest RUN apk add --no-cache ca-certificates vips-tools ffmpeg COPY --from=backend /stash/stash /usr/bin/ ENV STASH_CONFIG_FILE=/root/.stash/config.yml EXPOSE 9999 ENTRYPOINT ["stash"] ================================================ FILE: docker/build/x86_64/Dockerfile-CUDA ================================================ # This dockerfile should be built with `make docker-cuda-build` from the stash root. ARG CUDA_VERSION=12.8.0 # Build Frontend FROM node:20-alpine AS frontend RUN apk add --no-cache make git ## cache node_modules separately COPY ./ui/v2.5/package.json ./ui/v2.5/pnpm-lock.yaml /stash/ui/v2.5/ WORKDIR /stash COPY Makefile /stash/ COPY ./graphql /stash/graphql/ COPY ./ui /stash/ui/ # pnpm install with npm RUN npm install -g pnpm RUN make pre-ui RUN make generate-ui ARG GITHASH ARG STASH_VERSION RUN BUILD_DATE=$(date +"%Y-%m-%d %H:%M:%S") make ui-only # Build Backend FROM golang:1.24.3-bullseye AS backend RUN apt update && apt install -y build-essential golang WORKDIR /stash COPY ./go* ./*.go Makefile gqlgen.yml .gqlgenc.yml /stash/ COPY ./graphql /stash/graphql/ COPY ./scripts /stash/scripts/ COPY ./pkg /stash/pkg/ COPY ./cmd /stash/cmd COPY ./internal /stash/internal # needed for generate-login-locale COPY ./ui /stash/ui/ RUN make generate-backend generate-login-locale COPY --from=frontend /stash /stash/ ARG GITHASH ARG STASH_VERSION RUN make flags-release flags-pie stash # Final Runnable Image FROM nvidia/cuda:${CUDA_VERSION}-base-ubuntu24.04 RUN apt update && apt upgrade -y && apt install -y \ # stash dependencies ca-certificates libvips-tools ffmpeg \ # intel dependencies intel-media-va-driver-non-free vainfo \ # python tools python3 python3-pip && \ # cleanup apt autoremove -y && apt clean && \ rm -rf /var/lib/apt/lists/* COPY --from=backend --chmod=555 /stash/stash /usr/bin/ # NVENC Patch RUN mkdir -p /usr/local/bin /patched-lib ADD --chmod=555 https://raw.githubusercontent.com/keylase/nvidia-patch/master/patch.sh /usr/local/bin/patch.sh ADD --chmod=555 https://raw.githubusercontent.com/keylase/nvidia-patch/master/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh ENV LANG=C.UTF-8 ENV NVIDIA_VISIBLE_DEVICES=all ENV NVIDIA_DRIVER_CAPABILITIES=video,utility ENV STASH_CONFIG_FILE=/root/.stash/config.yml EXPOSE 9999 ENTRYPOINT ["docker-entrypoint.sh", "stash"] # vim: ft=dockerfile ================================================ FILE: docker/build/x86_64/README.md ================================================ # Introduction This dockerfile is used to build a stash docker container using the current source code. This is ideal for testing your current branch in docker. Note that it does not include python, so python-based scrapers will not work in this image. The production docker images distributed by the project contain python and the necessary packages. # Building the docker container From the top-level directory (should contain `tools.go` file): ``` make docker-build ``` # Running the docker container ## Using docker-compose See the `README.md` file in `docker/production` for instructions on how to get docker-compose if needed. The `stash/build` container can be run with the `docker-compose.yml` file in `docker/production` by changing the `image` value to be `stash/build`. See the instructions in `docker/production` for how to run docker-compose. ## Using `docker run` After building the container: ``` docker run \ -e STASH_STASH=/data/ \ -e STASH_METADATA=/metadata/ \ -e STASH_CACHE=/cache/ \ -e STASH_GENERATED=/generated/ \ -v