Skip to content
New: Star-import, signal unraveling, Python 3.12 support, and more

# Installation

Info

VectorBT PRO is a totally different beast compared to the open-source version. In fact, the PRO version redesigns the underlying core to enable groundbreaking features.

To avoid using an outdated code, make sure to only import vectorbtpro!

## Requirements

### 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
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

Important

After a few months you may get an email from GitHub stating that your personal access token has expired. If so, please go over the steps above and generate a new token. This has nothing to do with the access to the vectorbtpro repository!

### 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.10

Activate the new environment:

    conda activate vectorbtpro

Note

You need to activate the environment every time you start a new terminal session.

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`.

Hint

It's highly recommended creating a new virtual environment solely for vectorbtpro, such as with Anaconda.

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"

Info

Whenever you are prompted for a password, paste the token that you generated in the previous steps.

To avoid re-entering the token over and over again, you can add it to your system or set an environment variable `GH_TOKEN` and then install the package as follows:

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

On some systems, such as macOS, the token is usually remembered automatically.

Read more on managing tokens here.

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://git@github.com/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 install -U git+https://github.com/polakowo/vectorbt.pro.git@v2024.1.30

### Specific branch

Append `@` followed by a branch name to the command.

For example, to install the `develop` branch:

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

### Google Colab

Set your GitHub username and token using `%env`:

    %env GH_USER=abcdef...
    %env GH_TOKEN=abcdef...

Warning

Make sure to delete this cell when sharing the notebook with others!

Install VectorBT PRO:

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

Restart the runtime, and you're all set!

### 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 git@github.com: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 git@github.com: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 git@github.com: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

Info

The use of the `-v` flag in the command mounts the current working directory on the host (`{PWD/work}` in the example command) as `/home/jovyan/work` in the container. The server logs appear in the terminal. Due to the usage of the flag --rm Docker automatically cleans up the container and removes the file system when the container exits, but any changes made to the `~/work` directory and its files in the container will remain intact on the host. The -it flag allocates pseudo-TTY.

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`

Note

Change the port if necessary.

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

Info

This won't rebuild the entire image, only the vectorbtpro installation step.

## 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.

Note

If the file name ends with `(1)` because there's already a file with the same name, make sure to remove the previous file and remove the `(1)` suffix from the newer one.

## Troubleshooting

- TA-Lib
- Jupyter Notebook and JupyterLab
- Apple M1
- 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

- "fatal error: 'H5public.h' file not found"
- "RuntimeError: CMake must be installed to build qdldl"

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings