OpenBB/website/content/terminal/quickstart/installation.md

sidebar_position, title

sidebar_position	title
1	Installation

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

The OpenBB Terminal can be directly installed on your computer via our installation program. Within this section, you are guided through the installation process and how to launch the program. If you struggle with the installation process, please don’t hesitate to reach us on Discord or visit our contact page.

OpenBB Terminal is available in all major platforms. With MacOS/Windows you can easily install with the installer (instructions below). It is also available to install on Linux with Docker or from source.

:::info Installation Instructions

Install on Windows

The process starts off by downloading the installer, see below for how to download the most recent release:

1. Go to the OpenBB website.
2. Click on the Download button in the Windows Installer section.

When the file is downloaded, use the following steps to run the OpenBB Terminal:

Step 1: Double-click the .exe file that got downloaded to your Downloads folder

You will most likely receive the error below stating “Windows protected your PC”. This is because the installer is still in beta phase, and the team has not yet requested verification from Windows.

Step 2: Click on More info and select Run anyway to start the installation process

Proceed by following the steps. Do note that if you wish to install the application to “Program Files” that you will have to run the resulting application as Administrator.

Step 3: Double-click on the application that appeared on your Desktop, you are now able to run the OpenBB Terminal

The first time this takes a bit longer to load, this can take up to a few minutes.

Install on macOS 🍎

The process starts off by downloading the installer, see below for how to download the most recent release:

1. Go to the OpenBB website.
2. Click on the Download button in the macOS Installer section.

When the DMG file is downloaded, use the following steps to run the OpenBB Terminal:

Step 1: Open the downloaded OpenBB Terminal.dmg and copy OpenBB Terminal folder into your Applications

Open the OpenBB Terminal.dmg file that got saved to your “Downloads” folder and drag the “OpenBB Terminal” folder into “Applications” folder. A link to the Applications folder is presented on the screen. Note that this should take some time as it is extracting the files from the .dmg file.

Step 2: Open the OpenBB Terminal app in the folder that you have just copied to your Applications.

During first launch if you get a message saying that the application can’t be launched, do the following: Right-Click the app and select Open. You will see a message saying that macOS was not able to check whether the application contains malicious software. Click Open to proceed.

Install with Docker Here are the steps to get OpenBBTerminal using the Docker containers that we provide:

1. Installing Docker and Docker Compose
2. Pulling and running OpenBBTerminal Docker Container
3. Configuring your X-server to show plots

Each of this steps need to be followed to have a working version of OpenBBTerminal.

We will detail these steps in the rest of this document.

1. Installing Docker and Docker Compose

INSTALL DOCKER

Installing Docker Desktop is an alternative way and has a Graphical User Interface built in with Docker Compose.

You can find Docker Desktop installation file for your OS here: Download Docker Desktop

START DOCKER

Once you have Docker installed and running, you can use the following command to check the state:

docker info

It should output a text like this one:

Client:
 Context:    default
 Debug Mode: false

Server:
 Containers: 14
  Running: 2
  Paused: 1
  Stopped: 10

If you see a message like the following, it most likely means you need to start Docker.

Open the docker desktop app in this case.

Server:
ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

2. Pulling and running OpenBBTerminal Docker Container

DOCKER COMPOSE

Here are the commands to use Docker Compose to pull and run the OpenBBTerminal Docker Container:

curl -o docker-compose.yaml https://raw.githubusercontent.com/OpenBB-finance/OpenBBTerminal/main/docker/docker-compose.yaml

docker compose run poetry

The command line with curl is downloading this file : docker-compose.yaml.

The docker-compose.yaml file is a configuration file telling Docker Compose:

• where to find OpenBBTerminal Docker Container
• how to run this container.

The second command runs Docker Compose on the service poetry defined in this docker-compose.yaml file.

This second command must be run in the same folder in which docker-compose.yaml file is.

DOCKER

If you don't have Docker Compose you can also use Docker directly to run the OpenBBTerminal Docker Container.

Here is the commands to run:

docker pull ghcr.io/openbb-finance/openbbterminal-poetry:X.Y.Z

docker run -v ~/.openbb_terminal/:/home/python/.openbb_terminal -v ~/OpenBBUserData:/home/python/OpenBBUserData -it --rm ghcr.io/openbb-finance/openbbterminal-poetry:X.Y.Z

Be sure to replace X.Y.Z with the version you want to pull and run.

Note for windows:

    Ignore this message if you are using Powershell or a more evolved interpreters. 
    If you are using the builtin Windows interpreter.
    Replace `~` by `%USERPROFILE%` in the command above.

3. Configuring your X-server to show plots

In order to display plots in the docker container, we need to configure the XServer on the host machine. Without this configuration the interactive charts will not be displayed.

On Windows

Download and install : VcXsrv

When running the program is important to check "Disable access control"

Run Docker Compose like this:

curl -o docker-compose.yaml https://raw.githubusercontent.com/OpenBB-finance/OpenBBTerminal/main/docker/docker-compose.yaml

docker compose run poetry

Or run Docker directly:

docker run -v ~/.openbb_terminal:/home/python/.openbb_terminal -v ~/OpenBBUserData:/home/python/OpenBBUserData -it --rm --env DISPLAY=host.docker.internal:0.0 ghcr.io/openbb-finance/openbbterminal-poetry:X.Y.Z

X-Server on macOS

Users familiar with Docker and X-Server can set the DISPLAY variable in the file setenv described above. If you use this approach remember to add :0 at the end of your inet address. E.g. DISPLAY=192.168.1.155:0.

For help setting up the X-Server continue reading:

Setting up X Quartz/X11

On macOS the X11 client of choice is XQuartz. On Windows it's Xming. XQuartz will be used as an example further on.

0. Install X Quartz from https://www.xquartz.org/
1. With X Quartz open: go to Preferences -> Security and make sure both options are enabled.

Adding the display for Docker

From the command prompt or terminal, run the following to add your local configuration to the list of allowed access control:

IP=$(ifconfig | grep inet | grep -v -e "127.0.0.1" | awk '$1=="inet" {print $2}')
xhost + $IP

Now we can run the docker container, adding the display to the environment:

docker run -v ~/.openbb_terminal/:/home/python/.openbb_terminal -v ~/OpenBBUserData:/home/python/OpenBBUserData -it --rm --env-file=path/to/setenv --env DISPLAY=$IP:0 ghcr.io/openbb-finance/openbbterminal-poetry:X.Y.Z

This container will be able to display all the same plots as the terminal interface.

X-Server on Linux Desktop

X-Server is default in Linux distribution. There is no need to install any clients.

Local docker container

We can use IPC socket to connect Desktop.

Add this setting to your .env file.

OPENBB_BACKEND=Qt5Agg

And run the following commands.

xhost +local:
docker run -it --rm --name openbb --env-file=./.env -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix ghcr.io/openbb-finance/openbbterminal-poetry:X.Y.Z
xhost -local:

If you're using remote docker host, you can connect with "ssh -X <FQDN/IP>".

Then run the previous docker command.

This installation type supports both Windows and Unix systems (Linux + MacOS).

NOTE for Windows users: Some not all Windows users would prefer to use an environment similar to what Linux and macOS users use. In this case it is easier to use Windows Subsystem for Linux (WSL). WSL emulates a Linux machine inside your Windows system. If this is the case - jump to the Installing WSL (Only for Windows users) section before proceeding.

Installing the terminal

These steps are common in all operating systems (Windows with or without WSL, MacOS or Linux).

This project supports Python 3.8 and 3.9. By default, the newly created virtual environment will use Python 3.9.13

Our current recommendation is to use this project with Anaconda's Python distribution - either full Anaconda3 Latest or Miniconda3 Latest (recommended). Several features in this project utilize Machine Learning. Machine Learning Python dependencies are optional. For MacOS systems, the "Miniconda3 MacOSX 64-bit" version that works on both Intel and M1 macs is recommended.

NOTE: We recommend using conda and poetry because it just works. You can use other python distributions and use raw pip instead of poetry but you will very likely bump into installation issues.

1. Install Miniconda

Miniconda is a python environment and package manager. It is required if you want to have the dependencies working straight away.

• Follow the link to the page with the latest installers for all platforms or click direct links to installer packages based on your operating system:

  • If you are using macOS click Miniconda for MacOS

  • If you are using WSL or Linux click Miniconda for Linux

  • If you are using a Raspberry PI click Miniconda for Raspberry PI

  • If you are using Windows click Miniconda for Windows.

    ONLY REQUIRED ON WINDOWS IF NOT USING WSL, Install/update Microsoft C++ Build Tools from here: https://visualstudio.microsoft.com/visual-cpp-build-tools/

  NOTE for macOS users: The link above gets you the Intel version of miniconda meaning if you're on an Apple Silicon powered machine you will be using the terminal through Apple's rosetta2 layer. We recommend sticking to this distribution for better compatibility until the dependency developers fully catch up with Apple's transition to Apple Silicon.

• After following the steps, confirm that you have it by opening a terminal and running: conda -V. The output should be something along the lines of: conda 22.9.0

2. Install CMake

CMake is required by several python modules.

On Linux or Raspberry Pi:

sudo apt update
sudo apt install -y gcc cmake

On macOS:

Check if you have homebrew installed by running brew --version

If you don't have homebrew installed run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install cmake

If you have homebrew installed run:

brew install cmake

On Windows:

If you have followed the instructions in step 1 of this guide CMake was installed as a part of you Microsoft C++ Build Tools

3. Install git

conda install -c anaconda git

4. Clone the Project

• Via HTTPS: git clone https://github.com/OpenBB-finance/OpenBBTerminal.git
• via SSH: git clone git@github.com:OpenBB-finance/OpenBBTerminal.git

5. Navigate into the project's folder

cd OpenBBTerminal/

6. Create Environment

You can name the environment whatever you want. Although you could use names such as: welikethestock, thisistheway or diamondhands, we recommend something simple and intuitive like obb. This is because this name will be used from now onwards.

Please note, the following setup has been confirmed to work for all OS (including M1) with the standard miniconda distribution. If you are using a different distribution, you will need to install it manually before proceeding.

conda env create -n obb --file build/conda/conda-3-9-env.yaml

Or, to include machine learning type:

conda env create -n obb --file build/conda/conda-3-9-env-full.yaml

Note: Using python 3.10+ can lead to undesirable functionality for certain commands.

7. Activate the virtual environment

conda activate obb

Note: At the end, you can deactivate it with: conda deactivate.

8. Install dependencies with poetry

Install the main dependencies with

poetry install

You are good to go with the core of the OpenBB Terminal. To install additional toolkits proceed with the following commands:

To install the Portfolio Optimization Toolkit run:

poetry install -E optimization

To install the Machine Learning Toolkit run:

poetry install -E prediction

To install both the Portfolio Optimization and the Machine Learning Toolkit run:

poetry install -E all

9. You're ready to use the terminal!

openbb

Or if you are old-fashioned run:

python terminal.py

NOTE: When you close the terminal and re-open it, the only command you need to re-call is conda activate obb before you call openbb again.

TROUBLESHOOT: If you are having troubles to install, check out the troubleshoot page. You can also reach for help on our discord.

Advanced User Install - Custom installation procedures

By default we advice using conda and poetry for environment setup and dependency management. Conda ships binaries for packages like numpy so these dependencies are not built from source locally by pip. Poetry solves the dependency tree in a way that the dependencies of dependencies of dependencies use versions that are compatible with each other.

If you are using a conda environment the build/conda folder contains multiple .yaml configuration files that you can choose from.

If you are using other python distributions we highly recommend that you use some virtual environment like virtualenv or pyenv for installing the terminal dependency libraries.

Requirements files that you can find in the project root:

• requirements.txt list all the dependencies without Machine Learning libraries
• requirements-full.txt list all the dependencies without Machine Learning libraries

You can install them with with pip

pip install -r requirements.txt

The dependency tree is solved by poetry.

Note: The libraries specified in the requirements files have been tested and work for the purpose of this project, however, these may be older versions. Hence, it is recommended for the user to set up a virtual python environment prior to installing these. This allows to keep dependencies required by different projects in separate places.

Installing WSL (Only for Windows users)

If you are using Windows you first you need to install WSL. The process is simple and a tutorial can be found here. Once you reach the section Update Linux on that tutorial, you should have a linux machine installed and can proceed to the next steps.

Since WSL installation is headless by default (i.e., you have only access to a terminal running a linux distribution) you need some extra steps to be able to visualize the charts produced by the terminal (more detailed tutorial here):

1. Dynamically export the DISPLAY environment variable in WSL2:

   # add to the end of ~/.bashrc file
   export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
   # source the file
   source ~/.bashrc
   

2. Download and install VcXsrv

3. When running the program is important to check "Disable access control"

After this, VcXsrv should be running successfully and we can proceed to terminal installation.

Update Terminal

The terminal is constantly being updated with new features and bug fixes, hence, for your terminal to be update, you can use git pull to get the latest changes:

git pull

If this fails due to the fact that you had modified some python files, and there's a conflict with the updates, you can use:

git stash

Then, re-run poetry install to get any new dependencies. Once installation is finished, you're ready to use the OpenBB Terminal again. If you stashed your changes previously, you can un-stash them with:

git stash pop

NOTE: When you close the terminal and re-open it, the only command you need to re-call is conda activate obb before you call openbb again.

:::