Setting Up SBT

Install SBT step by step on any OS and verify it works. One-time setup per computer.

SBT is a Python package stored in the GitLab Package Registry. Installing it takes about 15 minutes. You'll need:

  • Access to the Seek GitLab SBT repository (at least Guest access). Ask in #ic-help if you're not sure you have it.

  • A GitLab Personal Access Token (created in step 2)

  • Python 3.10 or 3.11 (installed in step 3)

Step 1: Open a terminal

  • Mac: press Cmd + Space, type terminal, hit Enter.

  • Windows: press the Windows key, type powershell, hit Enter.

  • Linux: press Ctrl + Alt + T on most distributions.

All commands below get typed into this window.

Terminal survival basics

You'll be pasting long commands and fixing tokens in the middle of them. These shortcuts save a lot of backspacing:

What you want

Mac (Terminal)

Windows (PowerShell)

Bring back the last command

Up arrow

Up arrow

Search past commands

Ctrl + R, then type part of it

Ctrl + R, then type part of it

Wipe the whole line

Ctrl + U

Esc

Delete one word back

Ctrl + W

Ctrl + Backspace

Jump word by word

Option + ←/→

Ctrl + ←/→

Jump to start / end of line

Ctrl + A / Ctrl + E

Home / End

Put cursor where you click

Option + click

(not available)

Autocomplete file names

Tab

Tab

Optional but recommended: VS Code

VS Code is the free editor Seek engineering uses, and it works on Mac, Windows, and Linux. It gives you a file explorer, colored syntax for the YAML/SQL/TOML files SBT apps are made of, and a built-in terminal: press Ctrl + ` (backtick) to open one right under your files. Every terminal command in this guide works the same there. If you'll be editing app files regularly, install it now and do the rest of this guide from its terminal.

Step 2: Create a GitLab Personal Access Token (PAT)

Follow GitLab's guide and select the read_api and read_registry scopes (the permissions the token grants). If GitLab offers a choice of token types, create the classic (legacy) personal access token, not the newer fine-grained kind; fine-grained tokens don't work with the package registry. Copy the token somewhere safe. You'll use it in step 4.

Treat your PAT like a password. Don't share it in screenshots, Slack messages, or tickets. If it's ever exposed, revoke it in GitLab immediately and create a new one.

PATs expire. GitLab tokens have an expiration date. If installs that used to work start failing with 401 Error, Credentials not correct, your token has probably expired. Create a new one and rerun the command.

Step 3: Install Python 3.11

SBT requires Python 3.10 or 3.11. Python 3.12 and newer are not supported and will fail with "No matching distribution found" errors.

  1. Go to the Python 3.11.9 download page.

  2. Scroll to the Files table. Ignore the "tarball" links; those are source code.

    • Mac: click macOS 64-bit universal2 installer (ends in .pkg).

    • Windows: click Windows installer (64-bit) (ends in .exe). On the first installer screen, check the box "Add python.exe to PATH" before clicking Install.

  3. Open the downloaded file and follow the installer.

Confirm it worked:

  • Mac/Linux: python3.11 --version

  • Windows: py -3.11 --version

You should see Python 3.11.9.

Step 4: Install SBT

Current recommended version: 1.0.10 (as of August 2026). Check release announcements before installing; if a newer version is recommended, use that number in the command below.

Run the command for your OS, replacing <your_personal_token> with the PAT from step 2.

Mac/Linux:

python3.11 -m pip install sbt==1.0.10 --index-url https://__token__:<your_personal_token>@gitlab.com/api/v4/projects/54902832/packages/pypi/simple

Windows:

py -3.11 -m pip install sbt==1.0.10 --index-url https://__token__:<your_personal_token>@gitlab.com/api/v4/projects/54902832/packages/pypi/simple

Two things worth knowing about this command: -m pip tells Python to use its own built-in installer, so the package lands in the right Python version (plain pip often points at the wrong Python, or doesn't exist). And ==1.0.10 "pins" one exact version; see Pin a specific version below.

Step 5: Verify the install

sbt --help

If you see a list of SBT commands, you're done installing.

Got command not found: sbt (Mac/Linux) or 'sbt' is not recognized (Windows)? The install worked, but your system doesn't know where to look.

  • Mac: run these two commands, then try again:

echo 'export PATH="/Library/Frameworks/Python.framework/Versions/3.11/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

  • Windows: rerun the Python installer, choose Modify, and enable "Add python to environment variables." Then close and reopen PowerShell.

Common install errors

What you see

What it means

Fix

command not found: pip

Your system doesn't have plain pip

Use python3.11 -m pip (Mac/Linux) or py -3.11 -m pip (Windows)

No matching distribution found for sbt (with 401 warnings above it)

Your PAT is wrong or expired, so GitLab showed zero versions

Create a fresh PAT (step 2) and rerun

No matching distribution found for sbt (no 401 warnings)

Your Python is 3.12 or newer

Install Python 3.11 (step 3) and rerun step 4

command not found: sbt / 'sbt' is not recognized

Python's program folder isn't on your PATH

Run the PATH fix in step 5

UserWarning: Config key 'pyproject_toml_table_header'... (and a similar toml_file warning) when running any sbt command

Harmless warning from a library SBT uses

Ignore it. Your command still runs normally

[notice] A new release of pip is available

pip offering to update itself

Safe to ignore. Not related to SBT

Checking which version you have: run python3.11 -m pip show sbt (Mac/Linux) or py -3.11 -m pip show sbt (Windows) and look for the Version: line. (sbt --version is not a command.)

Known issue (August 2026, remove this note once fixed): fresh installs currently fail on sbt run-app with a 422 Unprocessable Entity error due to a dependency conflict. If you hit it, run python3.11 -m pip install -U prefect and rerun. Details in Troubleshooting App Installs & Runs.

Why the command says ==1.0.10

Look closely at the install command: right after sbt comes ==1.0.10, with no spaces. That tells pip: install exactly this version, no other. This is called "pinning."

Why it matters: SBT never updates itself. You stay on the version you installed until you deliberately rerun the install command with a newer number. That's a feature, since your tools never change out from under you mid-project. The flip side: when a release is announced, upgrading is on you. Rerun step 4 with the new version number; pip swaps old for new in one step.

Some features require minimum versions (for example, model visibility needs 1.0.10+). Release announcements state the recommended version.

What else gets installed

Installing SBT also installs the other software SBT needs to run; you saw this as a long list scrolling by during the install. That list includes Amazon (AWS) tools SBT uses to upload your app files during builds. This is normal, and none of it needs any setup from you.

What's next

Your machine is ready. Everything from here happens inside a project: head to the Quickstart to create your first project and configure it.

Related articles