Command-line Interface Installation

Interaction with the platform takes place via the Python-based command-line interface (CLI) and the Python API.

Mac OS X

It is easiest to install the CLI using homebrew:

brew tap swissdatasciencecenter/renku
brew install renku

Installation with the script manager pipx

Install and execute Renku in an isolated environment using pipx. It will guarantee that there are no version conflicts with dependencies you are using for your work and research.

Note

This is the method of installation in the renku docker images, i.e. the default environment you use when you launch a JupyterLab session via the renku browser interface.

Install pipx and make sure that the $PATH is correctly configured.

$ python3 -m pip install --user pipx
$ pipx ensurepath

Once pipx is installed use following command to install renku.

$ pipx install renku
$ which renku
~/.local/bin/renku

Previously we have recommended to use pipsi. You can still use it or migrate to pipx.

Upgrading

To upgrade renku to the latest stable version:

$ pipx upgrade renku

To upgrade to the latest development version:

$ pipx upgrade --pip-args=--pre renku

If you run into dependency problems during the CLI installation, have a look at the CLI installation problems.

pip/pipenv

For development or if the above methods do not work for you, Renku can also be installed with pip or pipenv:

pip install --pre renku

If you want to have Renku as a project dependency, you may install it using pipenv in your project’s directory:

pipenv install --pre renku
pipenv shell

Installing from source

Using conda, we can very easily install renku from source into an isolated environment.

Bleeding-edge

To install the latest bleeding-edge version of Renku and keep it from polluting your application environment, an easy solution is to place it inside an isolated conda environment. If you don’t have conda already, you should install miniconda. Once you have it installed, you can run

conda create -y -n renku python=3.6
$(conda env list | grep renku | awk '{print $2}')/bin/pip install -e git+https://github.com/SwissDataScienceCenter/renku-python.git#egg=renku
mkdir -p ~/.renku/bin
ln -s "$(conda env list | grep renku | awk '{print $2}')/bin/renku" ~/.renku/bin/renku

This will create an isolated environment for renku and link the binary to .renku/bin in your home directory. If you want to use it, you should add this to your PATH:

export PATH=~/.renku/bin:$PATH

If you want it to be done automatically for your shell (bash), add it to .bashrc:

echo "export PATH=~/.renku/bin:$PATH" >> $HOME/.bashrc
source $HOME/.bashrc

When you want to update the installed version again, simply do

$(conda env list | grep renku | awk '{print $2}')/bin/pip install -e git+https://github.com/SwissDataScienceCenter/renku-python.git#egg=renku

Specific version

To install a specific version of renku the procedure is nearly identical the above, but instead of installing from source you install a version with pip. For example, after creating the conda environment as described in the previous section, you can install renku v0.3.0 with

$(conda env list | grep renku | awk '{print $2}')/bin/pip install renku==0.3.0

Note

You may get a ValueError: unknown locale: UTF-8 - see here for instructions on how to fix it.