Skip to main content

Installation Guide

Welcome! This page will help you set up a local Python development environment for working with the Treble SDK.

  • If you're comfortable with Python and virtual environments, jump straight to the TL;DR for the minimum installation requirements.
  • You can find videos of installations in the installation videos section.
  • The videos pair well with the tutorial in the full installation guide.

This setup guide is cross-platform and designed to support Windows, macOS, and Linux. If you are on a Windows machine, we recommend using Ubuntu with WSL. If you choose this approach, after installing WSL, you may follow the installation guide for the Linux/WSL OS.

Note!

These installation guides assume you have already downloaded your credential file and the installation file from the management portal sent to you in the onboarding email!

Installation videos​

Note! You can follow along with the videos by using the instructions of the next section.

Full installation guide​

The Treble SDK is a Python library and supports Python versions 3.10, 3.11, 3.12 and 3.13.

To check if you have a supported version of Python installed, write either of these lines in your terminal or command window:

Open the Terminal by pressing 'Command+Spacebar' and searching for 'Terminal'. Once the Terminal is open, type the following and press 'Enter'.

python --version
tip

If you have not used the terminal before, you may be prompted to install Xcode Command Line Tools in order to run this command. Follow the prompts in the terminal to install the package, and then try the previous prompts again.

If you don't already have Python on your machine, or if you have an older version, download and install Python.

Installing Python​

  1. Download a more recent Python version from http://www.python.org and follow the installation instructions.
  2. When the Finder opens the location of the python files, double click on the file "Update Shell Profile.command" to update the terminal.
  3. Close the earlier terminal windows, and in a new window, run the terminal command to verify a successful installation:
python --version

Setting up a virtual environment​

We recommend using a virtual environment when installing the SDK to keep dependencies isolated.

The virtual environment can be placed anywhere you want but we recommend placing it under ~/.venv/TrebleSDK on macOS or Linux/WSL and under C:\Users\<YourUsername>\venvs\TrebleSDK on Windows.

To create and activate a virtual environment named TrebleSDK:

In the terminal, run:

python3 -m venv ~/.venv/TrebleSDK 
source ~/.venv/TrebleSDK/bin/activate

To deactivate your virtual environment, run deactivate in your terminal/PowerShell.

Installing the SDK package​

Save the installation file (.whl) in your working directory.

If you are using a virtual environment, ensure it is activated before installing the SDK and its dependencies by running:

pip install treble_tsdk-<VERSION>-py3-none-any.whl

This will install the SDK and all dependencies in your current Python environment. Note that this might take a few minutes.

Optional dependencies​

Many of the examples in our documentation are available as Jupyter notebooks.

For the best experience with the example notebooks, install the Jupyter notebook kernel using:

pip install jupyter

Storing your credentials​

There are many ways to use the credential file (.cred) with the SDK, which are discussed in more detail in the Credentials Guide. The SDK will automatically check the following locations for credential files, so please make the appropriate directories and copy the credential file there.

~/.config/treble/tsdk.cred

Opening the example notebooks​

You may use any code interface to work with the SDK, but we recommend Visual Studio Code if you don't yet have a preferred IDE.

Using VSCode​

Open the working directory as a project in VSCode, and select your notebook (.ipynb). If this is your first time using VSCode, the IDE will suggest installing the "Python" extension.

  1. Use Ctrl+Shift+P to open the Command Palette, and search for "Select Interpreter". Choose the python environemnt you have installed the SDK within.
  2. Now press "Select Kernel". If you have not yet installed it, you will be prompted to install the "Jupyter" extension. Once the extension is installed,under the "Select Kernel" dialog choose "Python Environments". Select the python environment with the SDK installed.

Now you should be ready to run the examples provided in the Jupyter notebooks using VSCode.

TL;DR (Quick Start)​

  1. The SDK officially supports Python versions 3.10, 3.11, 3.12, and 3.13.
  2. The default credential storage location depends on the OS:
Windows: %userprofile%\AppData\Local\treble\tsdk\tsdk.cred or %userprofile%\AppData\Roaming\treble\tsdk\tsdk.cred
Linux: ~/.config/treble/tsdk.cred
Macos: ~/.config/treble/tsdk.cred or ~/Library/Application Support/treble/tsdk.cred
  1. Install the SDK and its dependencies by saving the .whl file in your working directory and running
pip install treble_tsdk-<VERSION>-py3-none-any.whl
  1. In your IDE of choice, or run the following Python commands to initialise the SDK for the first time.
from treble_tsdk.tsdk import treble
tsdk = treble.TSDK()