Set up a development environment
Requirements
Section titled “Requirements”- Python 3.13 or later.
- uv: installs the dependencies from
uv.lockand runs the tools. - Git.
- Docker, only to build the Linux AppImage or to preview this documentation.
Install
Section titled “Install”git clone https://github.com/SOKTeam/S.O.K.gitcd S.O.Kuv sync --extra devuv 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.
API keys
Section titled “API keys”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.
cp .env.example .env.env is ignored by git. Never commit it.
Run the app
Section titled “Run the app”uv run sokWhen 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.
Check your setup
Section titled “Check your setup”These are the checks the CI runs on every pull request:
uv run ruff check srcuv run ruff format --check srcuv run python tools/verify_i18n.pyuv run mypy --install-types --non-interactive src/sok --ignore-missing-imports --no-strict-optionaluv run ty check srcuv run pytest tests/The interface tests need a display. On a machine without one (a server, a
container), set QT_QPA_PLATFORM=offscreen.