# Install and update

## Installation

raw2md needs Python 3.11 to 3.14. For `raw2md-engine`, you need an NVIDIA GPU of the Turing generation or newer (GTX 16xx, RTX 20xx, and later cards) with 4 GB of VRAM or more and driver 580 or newer. Without such a card, or with `--cuda off`, the engine runs on the CPU. This mode works, but it is much slower.

Install the tool with [uv](https://docs.astral.sh/uv/getting-started/installation/):

```bash
uv tool install --python ">=3.11,<3.15" raw2md --torch-backend cu130
```

Or with `pip`:

```bash
pip install raw2md --extra-index-url https://download.pytorch.org/whl/cu130
```

Or straight from GitHub:

```bash
uv tool install --python ">=3.11,<3.15" git+https://github.com/MikeDolg/raw2md.git
```

Do not skip `--python` in the `uv` commands. Without it, `uv` takes the default Python. If that Python is newer than 3.14, the install fails or picks an old raw2md release, because `uv` ignores the upper bound of `requires-python`.

On Windows, do not skip `--torch-backend cu130` or `--extra-index-url`: without them, you get a `torch` build with no CUDA support, and `raw2md-engine` can then run on the CPU only.

To work with DOCX files, you need to install `pandoc` 3.1.9 or later separately:

```powershell
# Windows
winget install --source winget --exact --id JohnMacFarlane.Pandoc
```

```bash
# Ubuntu 25.10 and later
sudo apt install pandoc

# Ubuntu 22.04 and 24.04: the apt package is older than 3.1.9, so get pandoc from the releases page
curl -fsSLO https://github.com/jgm/pandoc/releases/download/3.10.1/pandoc-3.10.1-1-amd64.deb
sudo dpkg -i pandoc-3.10.1-1-amd64.deb
```

To work with DjVu files, you also need to install DjVuLibre separately. On Windows, use the [installer](https://sourceforge.net/projects/djvu/files/DjVuLibre_Windows/).

```powershell
# Windows: the installer does not add its folder to PATH, so this command does it
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";${env:ProgramFiles(x86)}\DjVuLibre", "User")
```

```bash
# Ubuntu
sudo apt install djvulibre-bin
```

When everything is in place, download the weights of the engine and check the installation. If CUDA is not available, `raw2md doctor` tells you why:

```bash
raw2md init
raw2md doctor
```

## Update

```bash
uv tool upgrade raw2md
```

If you have not edited `prompts.yaml` and `keywords.yaml`, delete them from `~/.raw2md` after the upgrade and run `raw2md init` to get the new versions: the old files replace the built-in ones, and `init` does not overwrite them.

After an upgrade from 0.1.x:

- The engine is now `raw2md-engine`. Write `-e raw2md-engine` instead of `-e marker`, and rename the `marker` section of `settings.json` to `raw2md-engine`.
- `raw2md resume` cannot continue a run that 0.1.x started. Start the run again.
- Run `raw2md init` to download the weights into `~/.raw2md/models`. The weights of 0.1.x stay in `%LOCALAPPDATA%\datalab\datalab\Cache\models` on Windows and in `~/.cache/datalab/models` on Linux. raw2md no longer uses that folder, so you can delete it.

## Uninstall

```bash
uv tool uninstall raw2md
```

The uninstall leaves `~/.raw2md`, the engine weights included, where it is.