Installing Pipeless 🛠️

You have two options when using Pipeless:

Install the requirements and Pipeless locally.
Use the Docker image which already ships all the required dependencies.

Installing locally 💻

If you face any issues please check the troubleshooting (opens in a new tab) section, if you can't find your issue feel free to contact us for help via a GitHub issue.

Requirements ☝️

Python.
Gstreamer 1.20.3. Verify with gst-launch-1.0 --gst-version.

💡

Please note that the pre-built binaries are linked to specific Python versions. 3.10 for Linux amd64, 3.8 for Linux arm64 and 3.12 for macOS. If your installed version is different provide --build to the installation script, or update your Python version to match the above one.

Install dependencies for Linux

Python:

sudo apt-get install python3 python3-pip

Gstreamer:

Follow the installation instructions here (opens in a new tab) or just run:

sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
    libgstreamer-plugins-bad1.0-dev gstreamer1.0-plugins-base \
    gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
    gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-tools \
    gstreamer1.0-x gstreamer1.0-alsa gstreamer1.0-gl gstreamer1.0-gtk3 \
    gstreamer1.0-qt5 gstreamer1.0-pulseaudio gstreamer1.0-rtsp libcairo2-dev libgirepository1.0-dev

Install dependencies for macOS

brew install python

Also, to install Gstreamer in macOS use the following instead of the upstream instructions to ensure all the required packages are installed:

brew install gstreamer

Installation 🛠️

The provided installation script grabs the latest Pipeless version from the pre-built releases and installs it locally. You can use the script to either install or upgrade your Pipeless version. In case there is not a pre-built binary for your target OS or architecture the script will try to build Pipeless from source. You can also force the build from source using the --build flag.

💡

Note the pre-built binaries of Pipeless are built against Python 3.12 for macOS, 3.10 for Linux amd64 and 3.8 for Linux arm64. If you have a different Python version either update it to the mentioned ones or provide the --build flag to the script to build Pipeless for your installed Python version

curl https://raw.githubusercontent.com/pipeless-ai/pipeless/main/install.sh | bash

Or you can fetch the script, and then execute it locally. It's well documented so that you can read through it and understand what it is doing before you run it.

curl -fsSL -o install_pipeless.sh https://raw.githubusercontent.com/pipeless-ai/pipeless/main/install.sh
chmod 700 install_pipeless.sh
./install_pipeless.sh

💡

Remember to add the commands shown at the end of the installation to your shell configuration file, so Pipeless can be run in future shell sessions.

Finally, test the installation with:

pipeless --help

Using Docker 🐋

No installation is required when using Docker, you just need to have docker installed.

docker run miguelaeh/pipeless --help

Find the whole container documentation here.

Building from source

Apart from the Pipeless dependencies listed in the requirements you need to install pkg-config and cargo.

💡

If Microsoft does not provide a ONNX runtime build for your target platform go to the next section. You can check the ONXX Runtime releases at: https://github.com/microsoft/onnxruntime/releases (opens in a new tab)

Once the dependencies are installed run the following from the root of the Pipeless repository:

Linux

export PIPELESS_INSTALL_DIR="${HOME}/.pipeless"
cargo build --all --release --manifest-path pipeless/Cargo.toml
mv pipeless/target/release/pipeless-ai pipeless/target/release/pipeless
strip pipeless/target/release/pipeless
mv pipeless/target/release/{pipeless,libonnxruntime*} "${PIPELESS_INSTALL_DIR}/"

Include PIPELESS_INSTALL_DIR in your PATH and LD_LIBRARY_PATH.

macOS

export PIPELESS_INSTALL_DIR="${HOME}/.pipeless"
cargo build --all --release --manifest-path pipeless/Cargo.toml
mv pipeless/target/release/pipeless-ai pipeless/target/release/pipeless
strip pipeless/target/release/pipeless
mv pipeless/target/release/{pipeless,libonnxruntime*} "${PIPELESS_INSTALL_DIR}/"
install_name_tool -add_rpath @executable_path "${PIPELESS_INSTALL_DIR}/pipeless"

Include PIPELESS_INSTALL_DIR in your PATH.

Building ONNX Runtime from source

When you build Pipeless it will automatically download and link to a pre-built ONNX Runtime library obtained from the Microsoft releases. However, it may happen that Microsoft does not release a pre-built library for your target platform. When that's the case, please follow the below instructions to build both ONNX Runtime and Pipeless.

First, clone the ONNX Runtime repo as follows and move to the proper branch:

git clone https://github.com/microsoft/onnxruntime.git
cd onnxruntime
git checkout v1.16.3
git submodule update

Then, build it as follows:

💡

If you get out-of-memory running the following command remove the --parallel option or change it to a low value such as --parallel 2. It will take significantly more time to build, but you will not run out of memory.

# You can remove CUDA and Cudnn flags if you do not plan to use CUDA.
bash build.sh --parallel --build_shared_lib --config Release --use_cuda --cuda_home /usr/local/cuda/ --cudnn_home /usr/lib/aarch64-linux-gnu/

Now let's move the built library into the Pipeless install directory. Run the following, still from inside the ONNX repo root:

mkdir ~/.pipeless
cp ./build/Linux/Release/libonnxruntime*.so ~/.pipeless/

Now, move out of the ONNX runtime repository and clone the Pipeless repository:

cd ..
git clone https://github.com/pipeless-ai/pipeless.git
cd pipeless

Build Pipeless with the following command, which will link it to the ONNX Runtime library you built before:

ORT_STRATEGY=system ORT_LIB_LOCATION=~/.pipeless/ cargo build --manifest-path pipeless/Cargo.toml --release
mv pipeless/target/release/pipeless-ai pipeless/target/release/pipeless
strip pipeless/target/release/pipeless
cp pipeless/target/release/pipeless ~/.pipeless/

Finally run the following so you can start using Pipeless:

For Linux:

export PATH="${HOME}/.pipeless:${PATH}"
export LD_LIBRARY_PATH="${HOME}/.pipeless:${LD_LIBRARY_PATH}"

For macOS:

export PATH="${HOME}/.pipeless:${PATH}"
install_name_tool -add_rpath @executable_path "${PIPELESS_INSTALL_DIR}/pipeless

💡

Copy paste the above export commands in your ~/.bashrc or whatever file you use so Pipeless can be used in future sessions. If on macOS you do NOT have to copy the install_name_tool command in your profile.

🚀 Getting Started 📂 Project Structure