Build from Source

Building rotki from source is for contributors and for users who want to run unreleased code from git branches. If you just want to use rotki, the packaged binaries are easier.

WARNING

Don't switch between unreleased git builds and official releases on the same data directory. Unreleased code has no forward-compatibility guarantees for the database schema.

Prerequisites

Before starting, ensure you have the following installed:

• Git
• Python 3.11.x
• uv — Python package manager
• Node.js — check frontend/package.json engines for the exact supported range
• pnpm — managed via corepack (see Installing pnpm)
• Rust / Cargo — needed to build the Colibri service locally

Get the source

Fork the rotki repository on GitHub, then clone your fork locally:

git clone https://github.com/your-user/rotki.git
cd rotki

This guide assumes you checked out the develop branch, which is the default for contributors.

Backend setup

The backend setup is the same across Linux, macOS, and Windows — install uv, then run uv sync --locked to create the development environment. OS-specific notes are below.

Install uv

Linux and macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install dependencies

From the rotki repo root:

uv sync --locked --group dev --group lint

This creates a .venv and installs the backend, dev, and lint dependency groups.

Verify the backend

Start the backend once to confirm it runs:

uv run python -m rotkehlchen

You should see:

rotki REST API server is running at: 127.0.0.1:5042

Stop it with Ctrl+C — we'll run everything together once the frontend is set up.

OS-specific notes

Install Homebrew first if you don't have it. Homebrew is used as a bootstrap for Python 3.11 and other toolchain dependencies.

Frontend setup

The frontend lives under frontend/ and uses pnpm.

Installing pnpm

The repo uses corepack to manage pnpm. Enable it and corepack will automatically use the version pinned in frontend/package.json under packageManager:

corepack enable pnpm
pnpm --version

Install dependencies

cd frontend
pnpm install --frozen-lockfile

Run rotki in development mode

From the frontend/ directory:

pnpm run dev

This starts the Electron app together with the backend, the Colibri service (if Cargo is available), and the frontend dev server. If VITE_BACKEND_URL is set in frontend/app/.env.development.local, the development proxy starts as well.

For browser-only development (no Electron), use:

pnpm run dev:web

See Working with the Frontend for environment variables, feature flags, and proxy configuration.

Packaging

To build a distributable package for your platform:

# Install packaging dependencies
uv sync --locked --group packaging

# Run the packaging script (works on all platforms)
uv run python ./package.py --build full

Nix

If you use Nix, create a flake.nix at the repo root with the following:

{
  description = "rotki project with uv-managed virtualenv";

  inputs = {
    nixpkgs.url          = "github:NixOS/nixpkgs/nixos-24.05";
    nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    flake-utils.url      = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils, ... }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};

        python311         = pkgs.python311;
        nodejsWithPython  = pkgs.nodejs.override { python3 = python311; };
        nodePackages      = pkgs.nodePackages.override { nodejs = nodejsWithPython; };
        pnpmWithPython311 = nodePackages.pnpm;

        devShell = pkgs.mkShell {
          name = "rotki-dev";
          buildInputs = [
            pkgs.gcc
            pkgs.stdenv.cc.cc.lib
            pkgs.bash
            pkgs.git
            pkgs.lzma
            pnpmWithPython311
            python311
            pkgs.uv
          ];

          shellHook = ''
            uv sync
            cd frontend
            pnpm install
            cd ..
          '';
        };
      in { inherit devShell; });
}

Then enter the development environment with:

nix develop
cd frontend
pnpm run dev:web

Building a Docker image

To build a Docker image from source using the repo's Dockerfile:

docker build \
    --build-arg ROTKI_VERSION=1.44.0 \
    --build-arg REVISION="$(git rev-parse HEAD)" \
    -t rotki .

ROTKI_VERSION is not optional. It becomes the backend package's fallback version, and without it the build fails late, during the PyInstaller step, with InvalidVersion: ''. Use the version you are building, or any valid version string if you only want an image to test with. REVISION is only reported by the running image and can be left out.

Debugging a container you built

The runtime image is distroless. It has no shell, no package manager and no coreutils, so the usual moves do not work:

docker exec rotki sh
# OCI runtime exec failed: exec failed: unable to start container process:
# exec: "sh": executable file not found in $PATH

ls, cat and friends fail the same way. What does work:

• docker exec rotki /opt/rotki/starling ctl status for the state of the supervised processes.
• docker top rotki for the process list.
• Reading the data and log volumes from the host side of the bind mount rather than from inside the container.

If you genuinely need a shell in there, build yourself a debug image. There is no published :debug tag, deliberately, so layer one on top of the image you just built:

FROM rotki:latest
COPY --from=busybox:1.37-uclibc /bin/busybox /bin/busybox

docker build -t rotki:debug -f Dockerfile.debug .
docker exec -it rotki /bin/busybox sh

Inside that shell the applets are not on PATH as separate commands, so call them through busybox: busybox ls /opt/rotki, busybox cat /logs/rotki.log. Keep this for local debugging; do not run a busybox-carrying image in production, since it hands anything that gets in the shell the image was built without.

Troubleshooting

Blank screen when running the dev server

If you get a blank screen on Electron when starting the dev server, check the console for a syntax-error message:

If you see one, go to Help → Clear Cache, then View → Force Reload. If the issue persists, follow the frontend troubleshooting steps.

Windows build tool errors

If uv sync fails on Windows with errors like Microsoft Visual C++ 14.0 is required, the Visual Studio Build Tools aren't installed correctly. Make sure you selected the Desktop development with C++ workload when installing — see the prerequisites above.