From 2ea26581d3992fae80762bf23d3edc57542e34cb Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 18 Nov 2025 02:50:05 +0000 Subject: [PATCH 1/3] Update CLI installation to use 'uv tool install openhands' This change updates the CLI installation documentation to recommend using 'uv tool install openhands' instead of 'uvx --python 3.12 openhands'. Benefits: - More efficient: avoids re-downloading and rebuilding each time - Easier to upgrade: users can run 'uv tool upgrade openhands' - Simpler usage: after installation, just run 'openhands' directly Updated files: - openhands/usage/run-openhands/cli-mode.mdx - openhands/usage/run-openhands/local-setup.mdx - openhands/usage/run-openhands/gui-mode.mdx - openhands/usage/windows-without-wsl.mdx --- openhands/usage/run-openhands/cli-mode.mdx | 24 +++++++++++++------ openhands/usage/run-openhands/gui-mode.mdx | 2 +- openhands/usage/run-openhands/local-setup.mdx | 16 ++++++++++--- openhands/usage/windows-without-wsl.mdx | 16 +++++++++++-- 4 files changed, 45 insertions(+), 13 deletions(-) diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx index 45767f6fa..8ae7db769 100644 --- a/openhands/usage/run-openhands/cli-mode.mdx +++ b/openhands/usage/run-openhands/cli-mode.mdx @@ -28,20 +28,30 @@ configuration format has changed. Requires Python 3.12+ and uv installed. + **Install OpenHands:** ```bash - uvx --python 3.12 openhands + uv tool install openhands ``` - + **Run OpenHands:** + ```bash + openhands + ``` + + **Upgrade OpenHands:** + ```bash + uv tool upgrade openhands + ``` + + - Add the following to your shell configuration file (`.bashrc`, `.zshrc`, etc.): + If you want shorter commands, add the following to your shell configuration file (`.bashrc`, `.zshrc`, etc.): ```bash - alias openhands="uvx --python 3.12 openhands" - alias oh="uvx --python 3.12 openhands" + alias oh="openhands" ``` - After adding these lines, reload your shell configuration with `source ~/.bashrc` or `source ~/.zshrc` (depending on your shell). + After adding this line, reload your shell configuration with `source ~/.bashrc` or `source ~/.zshrc` (depending on your shell). @@ -99,7 +109,7 @@ configuration format has changed. --add-host host.docker.internal:host-gateway \ --name openhands-cli-$(date +%Y%m%d%H%M%S) \ python:3.12-slim \ - bash -c "pip install uv && uvx --python 3.12 openhands" + bash -c "pip install uv && uv tool install openhands && openhands" ``` The `-e SANDBOX_USER_ID=$(id -u)` is passed to the Docker command to ensure the sandbox user matches the host user’s diff --git a/openhands/usage/run-openhands/gui-mode.mdx b/openhands/usage/run-openhands/gui-mode.mdx index f248e6a9a..d5ea1980c 100644 --- a/openhands/usage/run-openhands/gui-mode.mdx +++ b/openhands/usage/run-openhands/gui-mode.mdx @@ -15,7 +15,7 @@ You can launch the OpenHands GUI server directly from the command line using the **Prerequisites**: You need to have the [OpenHands CLI installed](/usage/run-openhands/cli-mode) first, OR have `uv` -installed and run `uvx --python 3.12 openhands serve`. Otherwise, you'll need to use Docker +installed and run `uv tool install openhands`. Otherwise, you'll need to use Docker directly (see the [Docker section](#using-docker-directly) below). diff --git a/openhands/usage/run-openhands/local-setup.mdx b/openhands/usage/run-openhands/local-setup.mdx index a67f45808..a2d760357 100644 --- a/openhands/usage/run-openhands/local-setup.mdx +++ b/openhands/usage/run-openhands/local-setup.mdx @@ -76,20 +76,30 @@ We recommend using [uv](https://docs.astral.sh/uv/) for the best OpenHands exper See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for the latest installation instructions for your platform. +**Install OpenHands**: +```bash +uv tool install openhands +``` + **Launch OpenHands**: ```bash # Launch the GUI server -uvx --python 3.12 openhands serve +openhands serve # Or with GPU support (requires nvidia-docker) -uvx --python 3.12 openhands serve --gpu +openhands serve --gpu # Or with current directory mounted -uvx --python 3.12 openhands serve --mount-cwd +openhands serve --mount-cwd ``` This will automatically handle Docker requirements checking, image pulling, and launching the GUI server. The `--gpu` flag enables GPU support via nvidia-docker, and `--mount-cwd` mounts your current directory into the container. +**Upgrade OpenHands**: +```bash +uv tool upgrade openhands +``` + If you prefer to use pip and have Python 3.12+ installed: diff --git a/openhands/usage/windows-without-wsl.mdx b/openhands/usage/windows-without-wsl.mdx index a75cb710e..c8f6e808a 100644 --- a/openhands/usage/windows-without-wsl.mdx +++ b/openhands/usage/windows-without-wsl.mdx @@ -163,10 +163,22 @@ After installation, restart your PowerShell session to ensure the environment va ### 3. Install and Run OpenHands -After installing the prerequisites, you can install and run OpenHands with: +After installing the prerequisites, install OpenHands with: ```powershell -uvx --python 3.12 openhands +uv tool install openhands +``` + +Then run OpenHands: + +```powershell +openhands +``` + +To upgrade OpenHands in the future: + +```powershell +uv tool upgrade openhands ``` ### Troubleshooting CLI Issues From eb9fd6509431da64f56bb758522b233e0d93071d Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 18 Nov 2025 02:53:05 +0000 Subject: [PATCH 2/3] Remove shell aliases section - no longer needed with uv tool install Since 'uv tool install openhands' automatically makes the command available system-wide as 'openhands', shell aliases are no longer necessary. --- openhands/usage/run-openhands/cli-mode.mdx | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx index 8ae7db769..bbf44ce9e 100644 --- a/openhands/usage/run-openhands/cli-mode.mdx +++ b/openhands/usage/run-openhands/cli-mode.mdx @@ -42,18 +42,6 @@ configuration format has changed. ```bash uv tool upgrade openhands ``` - - - - If you want shorter commands, add the following to your shell configuration file (`.bashrc`, `.zshrc`, etc.): - - ```bash - alias oh="openhands" - ``` - - After adding this line, reload your shell configuration with `source ~/.bashrc` or `source ~/.zshrc` (depending on your shell). - - 1. Download the executable binary from From 420b33d8437b40006996f4757099abb369d51369 Mon Sep 17 00:00:00 2001 From: Xingyao Wang Date: Tue, 18 Nov 2025 11:04:19 +0800 Subject: [PATCH 3/3] Update openhands/usage/run-openhands/gui-mode.mdx --- openhands/usage/run-openhands/gui-mode.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openhands/usage/run-openhands/gui-mode.mdx b/openhands/usage/run-openhands/gui-mode.mdx index d5ea1980c..48cb8136a 100644 --- a/openhands/usage/run-openhands/gui-mode.mdx +++ b/openhands/usage/run-openhands/gui-mode.mdx @@ -15,7 +15,7 @@ You can launch the OpenHands GUI server directly from the command line using the **Prerequisites**: You need to have the [OpenHands CLI installed](/usage/run-openhands/cli-mode) first, OR have `uv` -installed and run `uv tool install openhands`. Otherwise, you'll need to use Docker +installed and run `uv tool install openhands` and `openhands server`. Otherwise, you'll need to use Docker directly (see the [Docker section](#using-docker-directly) below).