Skip to content

Set up a development environment

  • Python 3.13 or later.
  • uv: installs the dependencies from uv.lock and runs the tools.
  • Git.
  • Docker, only to build the Linux AppImage or to preview this documentation.
Terminal window
git clone https://github.com/SOKTeam/S.O.K.git
cd S.O.K
uv sync --extra dev

uv sync creates .venv/ and installs the exact versions from uv.lock. The dependencies of the core need no Qt; the extras add the rest:

Extra Contents
desktop PySide6 and pypresence, for the desktop app
server FastAPI, uvicorn and argon2-cffi, for S.O.K Server
dev desktop, server, pytest, pytest-qt, pytest-asyncio, httpx2, ruff, mypy, ty, python-dotenv
docs griffe, which describes the package for the API reference
build desktop, Nuitka and the packaging tools

Combine them as needed, for example uv sync --extra dev --extra docs.

The web interface of S.O.K Server (web/) also needs Node 24 and npm ci in web/ (see The web project). The desktop app does not.

Most databases need a key. Copy .env.example to .env at the repository root and fill in the keys you have. Deezer, MusicBrainz and Open Library work without one.

Terminal window
cp .env.example .env

.env is ignored by git. Never commit it.

Terminal window
uv run sok

When it runs from source, S.O.K keeps its files in the repository:

File Location
Settings data/config.json
Log logs/sok.log

Both folders are ignored by git. Set SOK_LOG_LEVEL=DEBUG for a more detailed log. Every setting and variable is listed in Settings and environment.

These are the checks the CI runs on every pull request:

Terminal window
uv run ruff check src
uv run ruff format --check src
uv run python tools/verify_i18n.py
uv run mypy --install-types --non-interactive src/sok --ignore-missing-imports --no-strict-optional
uv run ty check src
uv run pytest tests/

The interface tests need a display. On a machine without one (a server, a container), set QT_QPA_PLATFORM=offscreen.

Built with Kiln