Installation¶

Requirements¶

Authentication¶

Option 1: Token¶

After you've been added to the list of collaborators and accepted the repository invitation, the next step is to create a Personal Access Token for your GitHub account in order to access the PRO repository programmatically (from the command line or GitHub Actions workflows):

1. Go to https://github.com/settings/tokens
2. Click on [Generate a new token (classic)]
3. Enter a name (such as "terminal")
4. Set the expiration to some fixed number of days
5. Select the repo scope

6. Generate the token and save it in a safe place

Option 2: Credential Manager¶

Alternatively, use Git Credential Manager instead of creating a personal access token.

Git¶

If you don't have Git, install it.

TA-Lib¶

To use TA-Lib for Python, you need to install the actual library. Follow these instructions.

How to install TA-Lib in Google Colab?

Recommendations¶

Windows¶

If you're on Windows, it's recommended to use WSL for development.

New environment¶

If you plan to use vectorbtpro locally, it's recommended to establish a new environment solely for vectorbtpro.

Conda¶

The easiest way is to download Anaconda, which has a graphical installer and comes with many popular data science packages required by vectorbtpro such as NumPy, Pandas, Plotly, and more.

After the installation, create a new environment:

conda create --name vectorbtpro python=3.11

Activate the new environment:

conda activate vectorbtpro

You should now see vectorbtpro in the list of all environments and being active (notice *):

conda info --envs

You can now proceed with the installation of the actual package.

IDE¶

If you primarily work with an IDE, you can create a separate environment for each project. Here is how to create a new environment with PyCharm. The same but for Visual Studio Code is explained here.

With pip¶

The PRO version can be installed with pip.

Uninstall the open-source version if installed:

pip uninstall vectorbt

HTTPS¶

Install the base PRO version (with recommended dependencies) using git+https:

pip install -U "vectorbtpro[base] @ git+https://github.com/polakowo/vectorbt.pro.git"

pip install -U "vectorbtpro[base] @ git+https://${GH_TOKEN}@github.com/polakowo/vectorbt.pro.git"

Base version without TA-Lib:

pip install -U "vectorbtpro[base-no-talib] @ git+https://github.com/polakowo/vectorbt.pro.git"

Lightweight version (with only required dependencies):

pip install -U git+https://github.com/polakowo/vectorbt.pro.git

For other optional dependencies, see pyproject.toml.

SSH¶

To install the base version with git+ssh:

pip install -U "vectorbtpro[base] @ git+ssh://[email protected]/polakowo/vectorbt.pro.git"

See Connecting to GitHub with SSH.

Updating¶

Whenever a new version of vectorbtpro is released, the package will not update by itself - you need to install the update. Gladly, you can use the same exact command that you used to install the package to also update it.

Specific release¶

Append @ followed by a release name to the command.

For example, to install the release v2024.1.30:

pip uninstall vectorbtpro  # (1)!
pip install git+https://github.com/polakowo/[email protected]

1. If you have some other release of VBT PRO installed

Specific branch¶

Append @ followed by a branch name to the command.

For example, to install the develop branch:

pip install --upgrade --force-reinstall git+https://github.com/polakowo/vectorbt.pro.git@develop

As Python dependency¶

With setuptools adding vectorbtpro as a dependency to your Python package can be done by listing it in setup.py or in your requirements files:

# setup.py
setup(
    # ...
    install_requires=[
        "vectorbtpro @ git+https://github.com/polakowo/vectorbt.pro.git"
    ]
    # ...
)

With git¶

Of course, you can pull vectorbtpro directly from git:

git clone https://github.com/polakowo/vectorbt.pro.git vectorbtpro

git clone [email protected]:polakowo/vectorbt.pro.git vectorbtpro

Install the package:

pip install -e vectorbtpro

Shallow clone¶

The command above takes around 1GB of disk space, to create a shallow clone:

git clone https://github.com/polakowo/vectorbt.pro.git vectorbtpro --depth=1

git clone [email protected]:polakowo/vectorbt.pro.git vectorbtpro --depth=1

To convert the clone back into a complete one:

git pull --unshallow

With Docker¶

Using Docker is a great way to get up and running in a few minutes, as it comes with all dependencies pre-installed.

Docker image of vectorbtpro is based on Jupyter Docker Stacks - a set of ready-to-run Docker images containing Jupyter applications and interactive computing tools. Particularly, the image is based on jupyter/scipy-notebook, which includes a minimally-functional JupyterLab server and preinstalled popular packages from the scientific Python ecosystem, and extends it with Plotly and Dash for interactive visualizations and plots, and vectorbtpro and most of its optional dependencies. The image requires the source of vectorbtpro to be available in the current depository.

Before proceeding, make sure to have Docker installed.

Launch Docker using Docker Desktop.

Building¶

Clone the vectorbtpro repository (if not already). Run this from a directory where you want vectorbtpro to reside, for example, in Documents/GitHub:

git clone [email protected]:polakowo/vectorbt.pro.git vectorbtpro --depth=1

Go into the directory:

cd vectorbtpro

Build the image (can take some time):

docker build . -t vectorbtpro

Create a working directory inside the current directory:

mkdir work

Running¶

Start a container running a JupyterLab Server on the port 8888:

docker run -it --rm -p 8888:8888 -v "$PWD/work":/home/jovyan/work vectorbtpro

Alternatively, if the port 8888 is already in use, use another port (here 10000):

docker run -it --rm -p 10000:8888 -v "$PWD/work":/home/jovyan/work vectorbtpro

Once the server has been launched, visit its address in a browser. The address is printed in the console, for example: http://127.0.0.1:8888/lab?token=9e85949d9901633d1de9dad7a963b43257e29fb232883908

This will open JupyterLab where you can create a new notebook and start working with vectorbtpro

To make use of any files on the host, put them into to the working directory work on the host and they will appear in the file browser of JupyterLab. Alternatively, you can drag and drop them directly into the file browser of JupyterLab.

Stopping¶

To stop the container, first hit Ctrl+C, and then upon prompt, type y and hit Enter

Updating¶

To upgrade the Docker image to a new version of vectorbtpro, first, update the local version of the repository from the remote:

git pull

Then, rebuild the image:

docker build . -t vectorbtpro

Manually¶

In case of connectivity issues, the package can be also installed manually:

1. Go to https://github.com/polakowo/vectorbt.pro
2. Click on the Code dropdown button and then "Download ZIP"
3. Unzip the downloaded archive
4. Open the unzipped folder using terminal
5. Install the package using pip:

pip install ".[base]"

Custom release¶

To install a custom release:

1. Go to https://github.com/polakowo/vectorbt.pro/releases
2. Select a release
3. Download the file with the suffix .whl
4. Open the folder with the wheel file using terminal
5. Install the wheel using pip:

pip install wheel
pip install "filename.whl[base]"

Replace filename with the actual file name.

Google Colab¶

Notebook

Troubleshooting¶

• TA-Lib
• Jupyter Notebook and JupyterLab
• Apple M1
• "fatal error: 'H5public.h' file not found"
• "RuntimeError: CMake must be installed to build qdldl"
• pybind11:

If you're getting the error "ModuleNotFoundError: No module named 'pybind11'", install pybind11 prior to the installation of vectorbtpro:

pip install pybind11

• llvmlite:

If you're getting the error "Cannot uninstall 'llvmlite'", install llvmlite prior to the installation of vectorbtpro:

pip install --ignore-installed 'llvmlite'

• Plotly:

If image generation hangs (such as when calling show_svg()), downgrade the Kaleido package:

pip install kaleido==0.1.0post1

• osqp:

If you're on a Mac and encountering an error during the installation of the osqp package, install cmake:

brew install cmake