Dream Engines

Install

BASH
pip install dream-engine

Requires Python ≥3.10. The base install pulls three runtime dependencies:

  • httpx>=0.27,<1.0 — HTTP transport
  • numpy>=2.0 — array shapes for the predict path
  • pillow>=10 — required when start_frame is np.ndarray / PIL.Image

Total wheel: ~35 KB; total install with deps: ~25 MB.

Optional extras

ExtraAddsWhen you need it
[decode]mediapy>=1.2 (pulls ffmpeg via system)accessing decoded rollout.frames as numpy.ndarray (T, H, W, 3) uint8
[dev]pytest, respx, mypy, ruff, pillowrunning the SDK's own test suite
BASH
pip install "dream-engine[decode]"
pip install "dream-engine[decode,dev]"

If you don't install [decode], you can still call rollout.save("out.mp4") — that just writes the bytes the server sent, no decoding involved. The decode happens lazily, only when you read rollout.frames.

Editable install from source

BASH
git clone https://github.com/kingjulio8238/dreamengine
cd dreamengine
pip install -e "./sdk/python[dev,decode]"

The SDK lives at sdk/python/; the engine itself is in the parent dreamengine/ package (separate dependency tree, requires torch).

Supported Pythons

The SDK is tested in CI against 3.10, 3.11, 3.12, 3.13 on Linux. macOS works out-of-the-box. Windows works under WSL2; native Windows support depends on mediapy's ffmpeg path resolution and is best-effort.

Verify the install

PYTHON
import dream
print(dream.__version__)     # e.g. "0.1.0"
print(dream.Client)
img, actions = dream.examples.dreamdojo_grasp()
print(img.shape, actions.shape)   # (480, 640, 3) (48, 384)

If that prints clean, you're good. The next step is Authentication and Quickstart.

Why dream-engine not dream?

PyPI's dream namespace was already taken by an unrelated archived project, and dream-engine precisely describes what you're installing. The Python import name remains the short, clean import dream — the PyPI name and the import name are decoupled, like pip install opencv-python → import cv2.