---
sidebar_position: 1
---

# Installation

This guide will help you install CaDaR on your system. CaDaR supports Python 3.8+ and works on Linux, macOS, and Windows.

## Option 1: Install from PyPI (Recommended)

The easiest way to install CaDaR is using pip:

```bash
pip install cadar
```

This installs the pre-compiled binary wheel for your platform and Python version.

### Verify Installation

```python
import cadar

# Check version
print(f"CaDaR version: {cadar.__version__}")

# Test basic functionality
result = cadar.ara2bizi("سلام", darija="Ma")
print(f"Test: سلام → {result}")
assert result == "slam", "Installation check failed!"

print("✅ CaDaR is properly installed!")
```

## Option 2: Install from Source

If you need the latest development version or want to contribute, install from source:

### Prerequisites

1. **Python 3.8+**
   ```bash
   python --version  # Should be 3.8 or higher
   ```

2. **Rust toolchain** (1.70 or later)
   ```bash
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source $HOME/.cargo/env
   ```

3. **Maturin** (build tool for Rust+Python extensions)
   ```bash
   pip install maturin
   ```

### Build and Install

```bash
# Clone the repository
git clone https://github.com/Oit-Technologies/CaDaR.git
cd CaDaR

# Install in development mode
maturin develop

# Or build a release wheel
maturin build --release
pip install target/wheels/*.whl
```

## Option 3: Using Docker

For containerized environments:

```bash
# Pull the image
docker pull oittechnologies/cadar:latest

# Run with Python
docker run -it --rm oittechnologies/cadar:latest python
```

## Platform-Specific Notes

### Linux

No special requirements. The standard pip installation should work on most distributions.

```bash
# On Ubuntu/Debian, if needed:
sudo apt update
sudo apt install python3 python3-pip
```

### macOS

Install Xcode command line tools first:

```bash
xcode-select --install
```

Then install with pip as usual.

### Windows

Install Microsoft Visual C++ Build Tools:

1. Download from [Microsoft Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
2. Select "C++ build tools" during installation
3. Restart your terminal
4. Install with pip

## Using with Virtual Environments

It's recommended to use a virtual environment:

```bash
# Create virtual environment
python -m venv cadar-env

# Activate
# On Linux/macOS:
source cadar-env/bin/activate
# On Windows:
cadar-env\Scripts\activate

# Install CaDaR
pip install cadar
```

## Using with Different Python Versions

CaDaR supports Python 3.8 through 3.12:

```bash
# With specific Python version
python3.11 -m venv cadar-env
source cadar-env/bin/activate
pip install cadar
```

## Common Issues and Solutions

### Issue: "Failed building wheel for pyo3"

**Cause**: Missing Rust compiler or outdated version.

**Solution**:
```bash
# Install/update Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Update to latest
rustup update
```

### Issue: "Microsoft Visual C++ 14.0 is required" (Windows)

**Cause**: Missing C++ build tools.

**Solution**: Install [Microsoft Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/).

### Issue: Permission denied during installation

**Cause**: System-wide Python installation without permissions.

**Solution**:
```bash
# Option 1: User installation
pip install --user cadar

# Option 2: Use virtual environment
python -m venv cadar-env
source cadar-env/bin/activate
pip install cadar
```

### Issue: "RuntimeError: Python version mismatch"

**Cause**: Python version used to compile doesn't match runtime.

**Solution**: Ensure same Python version for both:
```bash
python --version  # Note the version
# Use that specific Python for installation
python3.11 -m pip install cadar
```

## Development Installation

If you're planning to contribute to CaDaR:

```bash
# Clone with recursive submodules
git clone --recursive https://github.com/Oit-Technologies/CaDaR.git
cd CaDaR

# Install in development mode
maturin develop

# Install development dependencies
pip install -e ".[dev]"

# Run tests to verify
cargo test
python -c "import cadar; print('✅ All good!')"
```

## Next Steps

Now that CaDaR is installed:

1. Try our [Quick Start Guide](./quickstart) for basic usage
2. Explore the [Python API](../user-guide/python-api)
3. Check out [Examples](../user-guide/examples)
4. Understand the [Architecture](../architecture/pipeline)

## Need Help?

- **Issues**: [GitHub Issues](https://github.com/Oit-Technologies/CaDaR/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Oit-Technologies/CaDaR/discussions)
- **Documentation**: [Full Documentation](https://oit-technologies.github.io/CaDaR/)