# Installation

## Requirements

- **Python Version**: 3.11 (Python 3.12+ also supported)
- **Package Manager**: [uv](https://docs.astral.sh/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.

```bash
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):**
```bash
# 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](https://docs.astral.sh/uv/) is the recommended installer for fastest performance.

```bash
# 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.11 ~/.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.

<details>
<summary>Pipx installation (may not work)</summary>

```bash
# 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
```
</details>

---

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

### Using conda

```bash
# Create and activate environment
conda create -n owi python=3.11
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)

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

# Create environment
mamba create -n owi python=3.11
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)

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

# Create environment
micromamba create -n owi python=3.11
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

```bash
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:

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

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

```bash
# 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):

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

### Interactive mode (debugging)

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

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

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

---

## Quick Verification

After installation, verify everything works:

```bash
# 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](./commands.md).

---

## Troubleshooting

### Python version issues

If you encounter errors with Python 3.12+, try creating with Python 3.11:
```bash
conda create -n owi python=3.11
```

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

```bash
uv venv --python 3.11 ~/.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:
```bash
owilix remote doctor
```

For more help, see the [troubleshooting guide](./troubleshooting.md).