Setup

Full installation guides by platform:

Install (2 minutes)

OpenRemap is on PyPI:

# uv (recommended)
uv tool install openremap

# or plain pip
pip install openremap

openremap is then available from any folder, no activation required.

Verify it worked:

openremap --version

Verify the install

Run these three commands in order. All three must succeed.

openremap --version    # prints the version number
openremap              # launches the TUI — confirm it opens without errors
openremap scan .       # dry-run scan of the current folder, nothing moves

Update & uninstall

# update (uv tool install)
uv tool upgrade openremap

# update (pip)
pip install --upgrade openremap

# uninstall (uv tool install)
uv tool uninstall openremap

# uninstall (pip)
pip uninstall openremap

For a development clone, delete the project folder — the virtual environment is self-contained inside .venv/.

Shell completion

Tab-complete command names and flags without reading the docs.

openremap --install-completion

Restart your terminal after running this. Then:

openremap i<Tab>          # → openremap identify
openremap scan --<Tab>    # → shows all --flags

Supported shells: bash, zsh, fish, PowerShell.

If installed via uv tool install, run the completion install once and it persists permanently. If installed via uv sync (development), run it inside the project:

uv run openremap --install-completion

Development setup

The essentials for cloning the repo and getting the full toolchain running:

git clone https://github.com/v-arapidis/openremap-core.git
cd openremap-core
uv sync
uv run maturin develop --release   # build the mandatory Rust extension
uv run pytest tests/ -q            # run the test suite

• The Rust native extension is mandatory — there is no pure-Python fallback. Run maturin develop --release after cloning and after any Rust change.
• In a development clone the command is only available inside the virtual environment: uv run openremap <command>, or activate the environment first (source .venv/bin/activate).

→ Full guide (structure, contribution workflow, debugging): Developer setup

Troubleshooting

openremap: command not found after uv tool install

uv installs tools into a platform-specific directory that must be on your PATH:

Linux / macOS — add to your shell profile and reload:

# bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# fish
fish_add_path ~/.local/bin

Windows — open a new PowerShell window and run the uv installer again; it sets the PATH automatically. Or add %APPDATA%\Local\uv\bin to your user PATH manually via System Properties → Environment Variables.

openremap: command not found after uv sync

Expected. After uv sync the command only exists inside the virtual environment, not on your global PATH. Use uv run openremap or activate the environment first:

source .venv/bin/activate      # macOS / Linux
.venv\Scripts\activate.bat     # Windows Command Prompt
.venv\Scripts\Activate.ps1     # Windows PowerShell

Commands behave differently than the repo suggests

You updated the source (or pulled new code) but the CLI still shows old behaviour, old flags, or old messages. The installed native extension is stale:

uv run maturin develop --release

This is required after any change to the Rust code — the extension is compiled, not interpreted.

uv: command not found

uv is not installed or not on your PATH. Follow the install guide for your platform: Windows · macOS / Linux

python: command not found or wrong Python version

uv manages its own Python and does not depend on the system Python. Let uv install the required version:

uv python install 3.10
uv sync

Permission denied on Linux / macOS

Do not use sudo with uv. Fix ownership of ~/.local and retry without sudo:

sudo chown -R $USER ~/.local
uv tool install openremap

Windows: running scripts is disabled

PowerShell's default execution policy blocks unsigned scripts. Run once:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then retry.

Tests failing after uv sync

uv run pytest tests/ -q

The test suite must be fully green on a clean install. If tests fail immediately after cloning, open an issue with the full output.

Quick-reference table