# How to Install OpenEnv from Hugging Face: Complete Setup Guide

> Learn how to install OpenEnv from Hugging Face with our complete setup guide. Follow simple steps to get your OpenEnv environment running quickly and efficiently.

- Repository: [Hugging Face/OpenEnv](https://github.com/huggingface/OpenEnv)
- Tags: getting-started
- Published: 2026-06-16

---

**Install OpenEnv by first running `pip install openenv` for the core library, then installing a specific environment client such as `pip install git+https://huggingface.co/spaces/openenv/echo_env` to interact with remote or local execution environments.**

OpenEnv is an end-to-end framework for creating, deploying, and interacting with isolated execution environments for agentic reinforcement-learning training. This guide walks you through how to install OpenEnv from Hugging Face, covering both the core package and individual environment clients that implement the Gymnasium-style API.

## Understanding the OpenEnv Architecture

OpenEnv uses a **client-server architecture** that separates the lightweight client library from containerized environment implementations. The core `openenv` package provides base classes and CLI tooling, while specific environments like `EchoEnv` or `CodingEnv` run inside Docker containers exposing FastAPI servers.

This design requires a two-step installation process. The core package in [`src/openenv/core/__init__.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/__init__.py) defines the `EnvClient` interface and communication protocols, while individual environments in the `envs/` directory implement the actual logic in [`src/openenv/core/env_server.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_server.py). Understanding this separation clarifies why you must install both components to run experiments.

## Step-by-Step Installation Guide

### Install the Core Package

Start by installing the base OpenEnv library from PyPI. This provides the client abstractions, Docker helpers, and command-line interface defined in [`src/openenv/cli/main.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/cli/main.py).

```bash
pip install openenv

```

This installs the framework's foundation, including the `EnvClient` class and WebSocket communication utilities, but does not include any runnable environments.

### Install an Environment Client

Next, install a specific environment implementation. The simplest starting point is the **Echo Environment**, which echoes back messages for testing connectivity:

```bash
pip install git+https://huggingface.co/spaces/openenv/echo_env

```

This command pulls the client code from the Hugging Face Space and installs the `EchoEnv` class exported in [`envs/echo_env/__init__.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/__init__.py). For development work on the coding environment, install in editable mode with development dependencies:

```bash
uv pip install -e "envs/coding_env[dev]"

```

### Verify Your Installation

Confirm that both packages installed correctly by checking imports and version information:

```bash
python -c "import openenv; print(openenv.__version__)"
python -c "from echo_env import EchoEnv; print('EchoEnv imported successfully')"

```

If both commands execute without errors, your OpenEnv installation from Hugging Face is ready for use.

## Working with OpenEnv Clients

Once installed, you can interact with environments either asynchronously (recommended for production) or synchronously (convenient for scripting).

### Async Usage (Recommended)

The primary interface uses async/await patterns for non-blocking communication with remote environments. This example connects to a hosted EchoEnv instance:

```python
import asyncio
from echo_env import CallToolAction, EchoEnv

async def main():
    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:
        # Initialize episode

        result = await client.reset()
        print(result.observation.echoed_message)
        
        # Execute action

        result = await client.step(
            CallToolAction(
                tool_name="echo_message", 
                arguments={"message": "Hello, OpenEnv!"}
            )
        )
        print(result.observation.result)
        print("Reward:", result.reward)

asyncio.run(main())

```

This pattern leverages the async implementation in [`src/openenv/core/client.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/client.py) (referenced by environment clients) to handle WebSocket communication efficiently.

### Synchronous Usage

For synchronous scripts or Jupyter notebooks, wrap the client using the `.sync()` method:

```python
from echo_env import CallToolAction, EchoEnv

with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client:
    result = client.reset()
    print(result.observation.echoed_message)
    
    result = client.step(
        CallToolAction(
            tool_name="echo_message",
            arguments={"message": "Sync call example"},
        )
    )
    print(result.observation.result)

```

The `.sync()` wrapper converts all async methods to blocking calls while maintaining the same API surface.

### Local Development Setup

To run environments locally without connecting to Hugging Face Spaces, clone the repository and install components in editable mode:

```bash
git clone https://github.com/huggingface/OpenEnv.git
cd OpenEnv
pip install -e .

cd envs/echo_env
pip install -e .

# Run the FastAPI server directly

uv run python -m echo_env.server.app --host 0.0.0.0 --port 8000

```

This workflow references the server implementation in [`envs/echo_env/server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/server/app.py), which extends the base server utilities in [`src/openenv/core/env_server.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_server.py).

## Key Files and Components

Understanding these source files helps troubleshoot installation issues and extend the framework:

- **[`README.md`](https://github.com/huggingface/OpenEnv/blob/main/README.md)** – Contains the architecture diagram, quick-start instructions, and CLI documentation at the repository root.

- **[`envs/echo_env/README.md`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/README.md)** – Specific setup instructions for the Echo environment, including available actions and observations.

- **[`src/openenv/core/__init__.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/__init__.py)** – Exports core abstractions including `EnvClient`, `StepResult`, and `CallToolAction` used by all environment implementations.

- **[`src/openenv/core/env_server.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_server.py)** – Provides FastAPI server utilities and the base environment server class that handles WebSocket connections and container lifecycle management.

- **[`src/openenv/cli/main.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/cli/main.py)** – Entry point for the `openenv` command-line tool, supporting commands like `init`, `push`, and `serve` for environment development.

- **[`envs/echo_env/__init__.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/__init__.py)** – Re-exports the `EchoEnv` client class and its associated Pydantic models for user convenience.

- **[`envs/echo_env/server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/server/app.py)** – Concrete FastAPI application implementing the Echo environment logic, demonstrating how to extend the base server for custom environments.

## Summary

- **Install the core framework** with `pip install openenv` to get client libraries and CLI tools.
- **Install specific environments** separately using `pip install git+https://huggingface.co/spaces/openenv/[env_name]` to interact with remote execution environments.
- **Use async patterns** for production workloads, or call `.sync()` for blocking, script-friendly interfaces.
- **Develop locally** by installing packages in editable mode and running FastAPI servers directly from `envs/[name]/server/app.py`.

## Frequently Asked Questions

### What is the difference between the core package and environment clients?

The **core package** (`openenv`) provides the infrastructure for WebSocket communication, Docker management, and base classes defined in [`src/openenv/core/__init__.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/__init__.py). **Environment clients** (like `echo_env`) are specific implementations that inherit from these base classes and connect to particular Docker containers or Hugging Face Spaces. You need both because the core contains no runnable environments, and environment clients depend on the core's communication protocols.

### Can I run OpenEnv environments without Docker?

Yes, though Docker provides the intended isolation. For local development, you can run the FastAPI server directly using `uv run python -m [env_module].server.app` as shown in the EchoEnv example. This executes the environment logic in [`envs/echo_env/server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/server/app.py) without containerization, though you must manually manage dependencies.

### How do I install a custom environment from a private Hugging Face Space?

Use the same `pip install git+https://huggingface.co/spaces/[username]/[space_name]` pattern, but ensure you have authenticated Hugging Face CLI access or include an access token in the URL: `git+https://[token]@huggingface.co/spaces/[username]/[space_name]`. The OpenEnv client in [`src/openenv/core/client.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/client.py) will handle the WebSocket connection regardless of whether the Space is public or private.

### Which Python versions are supported by OpenEnv?

OpenEnv requires **Python 3.9 or higher**. The core package uses modern async/await syntax and Pydantic v2 features, while environment implementations may have additional requirements specified in their individual [`pyproject.toml`](https://github.com/huggingface/OpenEnv/blob/main/pyproject.toml) files within the `envs/` directory.