Installation #

Requirements #

• Python Version: 3.12
• Package Manager: uv (recommended), pip, conda, mamba, or micromamba
• Operating Systems: Linux, macOS (Windows not officially tested)

Quick Install (Recommended) #

One-Line Install #

The easiest way to install owilix. Supports uv, conda, mamba, and pipx.

curl -fsSL https://openwebindex.net/owilix/install.sh | sh

What the script does:

• Detects available package managers (uv, conda, mamba, pipx)
• Lets you choose if multiple are available
• Installs uv if none found
• Creates a virtual/conda environment
• Installs owilix and dependencies
• Adds to PATH
• Checks for config migrations

Options (via environment variables):

# Force specific package manager
OWILIX_PM=uv curl -fsSL ... | bash

# Upgrade existing installation
OWILIX_UPGRADE=1 curl -fsSL ... | bash

# Custom install path (for uv/pipx)
OWILIX_PATH=~/my-owilix curl -fsSL ... | bash

If copy/paste inserts \|, remove the backslash and run with a normal pipe (|).

Manual Install with uv #

uv is the recommended installer for fastest performance.

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment and install owilix
uv venv --python 3.12 ~/.venv/owilix
source ~/.venv/owilix/bin/activate

# Install owilix and explicit URL dependency required by uv
uv pip install \
  "python-http-irods-client @ git+https://opencode.it4i.eu/lexis-platform/data/python-http-irods-client.git@1.1.2" \
  owilix \
  --index-url https://opencode.it4i.eu/api/v4/projects/92/packages/pypi/simple \
  --extra-index-url https://opencode.it4i.eu/api/v4/projects/107/packages/pypi/simple

# Add to PATH (optional)
echo 'export PATH="$HOME/.venv/owilix/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify installation
owilix --help

Using pipx (Isolated Environment) #

⚠️ Known Issue: pipx installation may fail due to git dependency python-http-irods-client. Use the uv venv method above instead.

# Install pipx if not installed
python3 -m pip install --user pipx
pipx ensurepath

# Install owilix
pipx install owilix \
  --index-url https://opencode.it4i.eu/api/v4/projects/92/packages/pypi/simple \
  --pip-args="--extra-index-url=https://opencode.it4i.eu/api/v4/projects/107/packages/pypi/simple"

# Verify
owilix --help

Method 1: Install with pip (in conda/mamba environment) #

Using conda #

# Create and activate environment
conda create -n owi python=3.12
conda activate owi

# Install packages
pip install py4lexis --index-url https://opencode.it4i.eu/api/v4/projects/107/packages/pypi/simple
pip install owilix --index-url https://opencode.it4i.eu/api/v4/projects/92/packages/pypi/simple

# Verify installation
owilix --help

Using mamba (faster than conda) #

# Install mamba if not installed
conda install -n base -c conda-forge mamba

# Create environment
mamba create -n owi python=3.12
mamba activate owi

# Install packages
pip install py4lexis --index-url https://opencode.it4i.eu/api/v4/projects/107/packages/pypi/simple
pip install owilix --index-url https://opencode.it4i.eu/api/v4/projects/92/packages/pypi/simple

# Verify
owilix --help

Using micromamba (minimal, standalone) #

# Install micromamba
"${SHELL}" <(curl -L micro.mamba.pm/install.sh)

# Create environment
micromamba create -n owi python=3.12
micromamba activate owi

# Install packages
pip install py4lexis --index-url https://opencode.it4i.eu/api/v4/projects/107/packages/pypi/simple
pip install owilix --index-url https://opencode.it4i.eu/api/v4/projects/92/packages/pypi/simple

# Verify
owilix --help

Upgrade #

pip install --upgrade py4lexis --index-url https://opencode.it4i.eu/api/v4/projects/107/packages/pypi/simple
pip install --upgrade owilix --index-url https://opencode.it4i.eu/api/v4/projects/92/packages/pypi/simple

Method 2: Install from Source #

For development or latest features:

# Clone the repository
git clone https://opencode.it4i.eu/openwebsearcheu-public/owi-cli.git
cd owi-cli

# Install with uv (recommended)
uv sync

# Run owilix
uv run owilix --help

# Or activate venv
source .venv/bin/activate
owilix --help

Method 3: Using Docker #

Pull the image #

docker pull opencode.it4i.eu:5050/openwebsearcheu-public/owi-cli:latest

# Verify
docker run --rm opencode.it4i.eu:5050/openwebsearcheu-public/owi-cli:latest --help

Run commands #

# Run with your configuration
docker run --rm -it \
  -v "$HOME/.owi:/home/owi/.owi" \
  opencode.it4i.eu:5050/openwebsearcheu-public/owi-cli:latest remote doctor

Set an alias #

Add to your shell profile (~/.bashrc, ~/.zshrc):

alias owilix='docker run --rm -it -v $HOME/.owi:/home/owi/.owi opencode.it4i.eu:5050/openwebsearcheu-public/owi-cli:latest'

Interactive mode (debugging) #

docker run --rm -it --entrypoint bash \
  opencode.it4i.eu:5050/openwebsearcheu-public/owi-cli:latest

# Inside container:
# owilix --help
# which owilix

If mixing Docker and native installations, ensure paths in `owilix.cfg` use `~` prefix for portability.

Quick Verification #

After installation, verify everything works:

# Check version
owilix --version

# Check config version
owilix config version

# Check connections
owilix remote doctor

# List available datasets
owilix remote ls all

For more usage, see the commands section.

Troubleshooting #

Python version issues #

OWILIX requires Python 3.12. If an existing environment uses another version, recreate it explicitly:

conda create -n owi python=3.12

uv conflicting URL error for python-http-irods-client #

If you see an error like: Requirements contain conflicting URLs for package python-http-irods-client

use the direct uv installation below and include python-http-irods-client as an explicit direct requirement:

uv venv --python 3.12 ~/.venv/owilix
source ~/.venv/owilix/bin/activate
uv pip install \
  "python-http-irods-client @ git+https://opencode.it4i.eu/lexis-platform/data/python-http-irods-client.git@1.1.2" \
  owilix \
  --index-url https://opencode.it4i.eu/api/v4/projects/92/packages/pypi/simple \
  --extra-index-url https://opencode.it4i.eu/api/v4/projects/107/packages/pypi/simple

Authentication issues #

If login fails, check that B2ACCESS credentials are valid:

owilix remote doctor

For more help, see the troubleshooting guide.