Installation¶

TagStudio provides executable releases as well as full access to its source code under the GPLv3 license.

Executables¶

To download executable builds of TagStudio, visit the Releases page of the GitHub repository and download the latest release for your system under the "Assets" section at the bottom of the release.

TagStudio has builds for Windows, macOS (Apple Silicon & Intel), and Linux. We also offer portable releases for Windows and Linux which are self-contained and easier to move around.

Package Managers¶

Installing with PIP¶

TagStudio is installable via PIP. Note that since we don't currently distribute on PyPI, the repository needs to be cloned and installed locally. Make sure you have Python 3.12 and PIP installed if you choose to install using this method.

The repository can be cloned/downloaded via git in your terminal, or by downloading the zip file from the "Code" button on the repository page.

git clone https://github.com/TagStudioDev/TagStudio.git

Once cloned or downloaded, you can install TagStudio with the following PIP command:

pip install .

pip install -e ".[dev]"

TagStudio can now be launched via the tagstudio command in your terminal.

Linux¶

Some external dependencies are required for TagStudio to execute. Below is a table of known packages that will be necessary.

Nix(OS)¶

For Nix(OS), the TagStudio repository includes a flake that provides some outputs such as a development shell and package.

Two packages are provided: tagstudio and tagstudio-jxl. The distinction was made because tagstudio-jxl has an extra compilation step for JPEG-XL image support. To give either of them a test run, you can execute nix run github:TagStudioDev/TagStudio#tagstudio. If you are in a cloned repository and wish to run a package with the context of the repository, you can simply use nix run with no arguments.

nix build can be used in place of nix run if you only want to build. The packages will only build if tests pass.

Want to add TagStudio into your configuration?

This can be done by first adding the flake input into your flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    tagstudio = {
      url = "github:TagStudioDev/TagStudio";
      inputs.nixpkgs.follows = "nixpkgs"; # Use the same package set as your flake.
    };
  };
}

Then, make sure you add the inputs context to your configuration:

{
  outputs =
    inputs@{ home-manager, nixpkgs, ... }:
      {
        nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
          system = "x86_64-linux";

          specialArgs = { inherit inputs; };
          modules = [
            ./configuration.nix

            home-manager.nixosModules.home-manager
            {
              home-manager = {
                useGlobalPkgs = true;
                useUserPackages = true;

                extraSpecialArgs = { inherit inputs; };
                users.USER.imports = [
                  ./home.nix
                ];
              };
            }
          ];
        };
      };
}

{
  outputs =
    inputs@{ nixpkgs, ... }:
      {
        nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
          system = "x86_64-linux";

          specialArgs = { inherit inputs; };
          modules = [
            ./configuration.nix
          ];
        };
      };
}

{
  outputs =
    inputs@{ home-manager, nixpkgs, ... }:
    let
      pkgs = import nixpkgs {
        system = "x86_64-linux";
      };
    in
    {
      homeConfigurations.USER = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;

        extraSpecialArgs = { inherit inputs; };
        modules = [
          ./home.nix
        ];
      };
    };
}

Finally, inputs can be used in a module to add the package to your packages list:

{ inputs, pkgs, ... }:

{
  home.packages = [
    inputs.tagstudio.packages.${pkgs.stdenv.hostPlatform.system}.tagstudio
  ];
}

{ inputs, pkgs, ... }:

{
  environment.systemPackages = [
    inputs.tagstudio.packages.${pkgs.stdenv.hostPlatform.system}.tagstudio
  ];
}

Don't forget to rebuild!

Third-Party Dependencies¶

FFmpeg/FFprobe¶

For audio/video thumbnails and playback you'll need FFmpeg installed on your system. If you encounter any issues with this, please reference our FFmpeg Help guide.

RAR Extractor¶

To generate thumbnails for RAR-based files (like .cbr) you'll need an extractor capable of handling them.

• On Linux you'll need to install either unrar (likely in you distro's non-free repository) or unrar-free from your package manager.

• On macOS unrar can be installed through Homebrew's rar formula.

  macOS "Privacy & Security" Popup

  On macOS, you may be met with a message similar to ""unrar" Not Opened. Apple could not verify "unrar" is free of malware that may harm your Mac or compromise your privacy" If you encounter this, then you'll need to go to the "Settings" app, navigate to "Privacy & Security", and scroll down to a section that says ""unrar" was blocked from use because it is not from an identified developer." Click the "Open Anyway" button to allow unrar to be used.

• On Windows you'll need to install either WinRAR or 7-zip and add their folder to you PATH.

  WinRAR License

  Both unrar and WinRAR require a license, but since the evaluation copy has no time limit you can simply dismiss the prompt.

ripgrep¶

A recommended tool to improve the performance of directory scanning is ripgrep, a Rust-based directory walker that natively integrates with our .ts_ignore (.gitignore-style) pattern matching system for excluding files and directories. Ripgrep is already pre-installed on some Linux distributions and also available from several package managers.