Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LLM, Agent, Conversation, Tool
✓ from openhands.sdk import LLM, Agent, Conversation, Tool
These are core components for building and running an OpenHands AI agent.
FileEditorTool, TaskTrackerTool, TerminalTool
✓ from openhands.tools.file_editor import FileEditorTool
from openhands.tools.task_tracker import TaskTrackerTool
from openhands.tools.terminal import TerminalTool
These are common tools used by OpenHands agents, imported from the 'openhands.tools' sub-package.
This quickstart demonstrates how to initialize an LLM, create an agent with basic tools (Terminal, FileEditor, TaskTracker), set up a conversation in the current working directory, and assign a simple file-writing task. Ensure `LLM_API_KEY` and optionally `LLM_MODEL` are set in your environment variables.
import os
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.task_tracker import TaskTrackerTool
from openhands.tools.terminal import TerminalTool
# NOTE: Replace with your actual LLM_API_KEY and desired model
llm = LLM(
model=os.environ.get("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
api_key=os.environ.get("LLM_API_KEY", ""), # Ensure LLM_API_KEY is set in your environment
base_url=os.environ.get("LLM_BASE_URL", None),
)
agent = Agent(
llm=llm,
tools=[
Tool(name=TerminalTool.name),
Tool(name=FileEditorTool.name),
Tool(name=TaskTrackerTool.name),
],
)
cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)
print("Sending task to agent...")
conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
print("Agent finished.")
openhands --version
Debug
Known issues
breakingOpenHands 1.0.0 introduced a 'new software-agent-sdk' and a complete architectural redesign, which broke compatibility with conversations and serialized agent sessions from pre-1.0.0 versions. The V0 API was also deprecated and removed on April 1, 2026.fixFor new projects, start with OpenHands 1.0.0 or later. For existing pre-1.0.0 projects, refer to the official migration guides to adapt to the new SDK and V1 API, as old conversations are not directly compatible.
affects: <1.0.0
gotchaWhen running OpenHands with a Docker sandbox, especially in self-hosted deployments or for remote access, ensure `WEB_HOST`, `SANDBOX_CONTAINER_URL_PATTERN`, and `OH_SANDBOX_USE_HOST_NETWORK=true` environment variables are correctly configured. Incorrect settings can lead to connection failures, sandbox errors, or CORS issues.fixConsult the 'Configuration Options' and 'Docker Sandbox' documentation for your OpenHands version to set up these environment variables appropriately for your deployment scenario. For example: `export WEB_HOST=http://your_ip:3000` and `export SANDBOX_CONTAINER_URL_PATTERN=http://your_ip:{port}`. affects: >=1.3.0
gotchaAn LLM API key (e.g., for Anthropic or OpenAI) is essential for OpenHands to function. Without a valid key configured, the agent cannot interact with the language model and will not be able to perform tasks.fixProvide your LLM API key via the `LLM_API_KEY` environment variable or configure it through the OpenHands UI settings. Also ensure `LLM_MODEL` and `LLM_BASE_URL` are set if using a non-default model or custom endpoint.
affects: All versions
deprecatedThe OpenHands V0 API was deprecated with the release of version 1.0.0 and was officially removed on April 1, 2026. Integrations relying on the V0 API will no longer work.fixMigrate any integrations using the V0 API to the V1 API, which is documented in the OpenHands Cloud API section.
affects: >=1.0.0 (removal in 1.x.x after 2026-04-01)
gotchaTools provided to an OpenHands agent are part of its initial system prompt and cannot be dynamically changed mid-conversation. To modify the set of tools available to an agent, a new conversation must be started, or conversation forking must be utilized.fixDesign your agent's toolset carefully at the start of a conversation. If different tools are needed for a new phase of work, initiate a new conversation or leverage conversation forking if supported in your environment.
affects: All versions using the SDK agent model
gotchaWhile `pip install openhands-ai` installs the SDK, the `openhands` CLI often has specific installation recommendations (e.g., using `uv` or Docker) to ensure the proper sandboxed runtime environment is configured, especially for local GUI or command-line execution.fixIf planning to use the OpenHands CLI or local GUI, refer to the official 'Getting Started' or 'CLI QuickStart' documentation for the recommended installation method, which might involve `uv tool install` or Docker commands, in addition to or instead of `pip install openhands-ai`.
affects: All versions, particularly for CLI users
Errors
Common errors & fixes
Launch docker client failed. Please make sure you have installed docker and started docker desktop/daemon.
OpenHands relies on Docker for its sandboxed runtime environment, and this error occurs when the Docker daemon is not running or is inaccessible to the OpenHands application.
fixEnsure Docker Desktop (on Windows/macOS) or the Docker daemon (on Linux) is running and accessible. You can verify this by running `docker ps` in your terminal. For Docker Desktop, also check settings like 'Allow the default Docker socket to be used' and 'Enable host networking' if applicable.
PermissionError: [Errno 13] Permission denied: '~/.openhands'
This error typically occurs when the user running OpenHands does not have the necessary read/write permissions for the `~/.openhands` directory, which OpenHands uses to store configuration and conversation history.
fixChange the ownership of the directory with `sudo chown <user>:<user> ~/.openhands` or update permissions using `sudo chmod 777 ~/.openhands`. Alternatively, if no previous data is needed, delete the directory, and OpenHands will recreate it with the correct permissions.
ERROR:root:<class 'httpx.ConnectTimeout'>: timed out
This error often indicates that OpenHands, running within a Docker container, cannot establish a network connection to an external LLM service (like Ollama) running on the host machine or another network location. This can be due to firewall issues, incorrect network configuration, or the LLM service not being properly exposed or running.
fixEnsure your LLM service is running and accessible (e.g., test with `curl http://localhost:[PORT]` from your host). If running OpenHands in Docker and connecting to a host service, use `http://host.docker.internal:[PORT_NUMBER]` for the LLM's base URL. Also, check firewall settings on your host to allow connections to the LLM port from Docker.
ImportError: cannot import name 'ResponseTextConfig' from 'openai.types.responses.response'
This `ImportError` usually arises from a version incompatibility or conflict between the installed `openai` library and `litellm` (a dependency of OpenHands-AI), or with OpenHands itself. Specifically, `ResponseTextConfig` might have been renamed or removed in a newer or older `openai` version than expected.
fixTry reinstalling or downgrading the `openai` and/or `litellm` packages to versions compatible with your OpenHands-AI installation. Checking the OpenHands-AI `pyproject.toml` or `requirements.txt` for specific dependency versions can help. A common fix is to update both `openai` and `litellm` to their latest compatible versions or to the versions specified by OpenHands.
ModuleNotFoundError: No module named 'agenthub'
This error indicates that the Python interpreter cannot find the `agenthub` module, which is a core part of OpenHands. This typically happens when OpenHands is not installed correctly, the Python environment is not set up properly, or you are trying to run components without the full OpenHands structure.
fixEnsure OpenHands is correctly installed, especially if you're using a development workflow. If building from source, make sure all dependencies are installed and the `PYTHONPATH` includes the OpenHands root directory. If using `pip`, ensure `pip install openhands-ai` was successful in your active environment.
Upgrade
Version history
1.11.0latest on PyPI · released Jul 9, 2026
Audit
Dependencies
pythonrequiredRequires Python versions >=3.12 and <3.14.