Skip to content

Installation ⊹ ࣪ ˖

Before you begin, we highly recommend creating a clean environment to avoid conflicts with pre-existing libraries. This ensures a reproducible installation. If you're already familiar with virtual environments, you can skip directly to Installation.

For this tutorial, we'll create a Python virtual environment (venv), but you can use any other environment manager of your choice (conda, pixi, etc.).

Requirements

  • Python 3.10 or higher (download here)
  • RAM: 4 GB (8 GB recommended)
  • Free disk space: ~2 GB for full installation

Note

On Windows, when running the Python installer, make sure to check "Add Python to PATH" to avoid issues in the following steps.

Optionally, if you prefer not to install anything on your computer or don't meet the requirements, you can also use Traitly remotely on Google Colab (requires a Google account). The free tier typically includes ~12 GB RAM and ~100 GB of local disk space. In that case, you can skip directly to the Google Colab tab in the installation section.

Before You Begin

All commands in this tutorial should be run in a terminal (also called command line or console). Here's how to access it on different operating systems:

  • macOS: Open the Terminal app (find it with Spotlight using Cmd + Space and typing "Terminal")
  • Linux: Open the Terminal app from the applications menu, or press Ctrl + Alt + T
  • Windows: Open PowerShell (search for it in the Start menu)
How to use the terminal?

For more information on using the terminal, here are two tutorials to get started:

Once the terminal is open, navigate to the folder where you want to host your project. If it doesn't exist yet, create it with: 

# Create folder with mkdir
mkdir ~/Documents/my-project

# Navigate to the folder
cd ~/Documents/my-project

This is where you'll save your virtual environment and your files.

Your project folder will look something like this: 

my-project/
├── traitly-env/       <- virtual environment (created in the following steps)
├── my_notebook.ipynb
├── images/
└── ...

Windows Directory

Replace ~ with your full user path, for example C:\Users\YourName\Documents\my-project, or simply right-click on the folder in File Explorer and select "Open in Terminal" to skip the navigation step.

Installation

1. Create a new Python environment:

You can replace traitly-env with any name you prefer.

python3 -m venv traitly-env

2. Activate the environment: 

source traitly-env/bin/activate

If activation was successful, (traitly-env) will appear at the beginning of your terminal prompt.

3. Install Traitly Get the latest version: 

pip install traitly

Or a specific one: 

pip install traitly==0.2.0

1. Create a new Python environment:

You can replace traitly-env with any name you prefer. 

py -m venv traitly-env

2. Activate the environment: 

traitly-env\Scripts\activate

If activation was successful, (traitly-env) will appear at the beginning of your terminal prompt.

3. Install Traitly

Get the latest version: 

pip install traitly

Or a specific one: 

pip install traitly==0.2.0

Important Note

Google Colab does not save sessions. Every time you close your browser or your session expires, you'll need to reinstall Traitly starting from step 3.

1. Create an account or sign in: Go to colab.research.google.com and sign in with your Google account. If you don't have one, you can create one for free at accounts.google.com.

2. Create a new notebook: Once inside, go to File -> New notebook in Drive. This will open a new Jupyter document in your browser.

3. Install Traitly:

In the first cell, copy and run the following command:

Get the latest version: 

!pip install traitly

Or a specific one: 

!pip install traitly==0.2.0

Optional Dependencies

By default, Traitly will only install the base package. Depending on your use case, you might need to install additional dependencies:

Extra Includes Command
pdf PDF to image conversion pip install "traitly[pdf]"
app PDF conversion + Shiny app pip install "traitly[app]"
dev Pytest + PytestCov pip install "traitly[dev]"

Not sure which to choose?

If you're unsure, we recommend installing app, since it includes everything you need to use Traitly's full functionality, including the interactive app.

Important

The quotes around the URL are necessary on macOS and Linux to prevent the terminal from incorrectly interpreting the [ and ] characters. On Windows they are optional, but recommended for consistency.

Verify Installation

Once installed, you can confirm everything is working correctly by running:

In the terminal: 

traitly --version

In Python or Jupyter Notebook: 

import traitly
print(traitly.__version__)

If the installation was successful, you should see the installed version number printed in the console.

Deactivate the Environment

When you finish working, you can deactivate the environment with: 

deactivate

Troubleshooting

1. pip not found after activating the environment: Try using pip3 instead of pip:

pip3 install traitly

Or reinstall Python making sure to check "Add Python to PATH" during installation (Windows).

2. Permission errors on macOS/Linux: Avoid using sudo pip install. Instead, make sure your virtual environment is properly activated before installing.