Registry / ai-ml / dora-search

dora-search

JSON →
library0.1.12pypypi✓ verified 24d ago

Dora Search is an experiment management tool developed by Facebook Research, designed to simplify grid searches and hyperparameter tuning for machine learning projects. It helps organize experiments, log results, and ensure reproducibility. Currently at version 0.1.12, it has an active development pace with frequent minor updates, focusing on robust experiment tracking and launch capabilities.

pip install dora-search
INSTALL
IMPORT
SIG · DORA-SEARCH
D
dora-search
ai-mlpythonv0.1.12
Install
68.0s avg
Import
6438ms
Disk
4736MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.12 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 75.8s
py 3.11
✕ build_error
✓ 71s
py 3.12
✕ build_error
✓ 65.1s
py 3.13
✕ build_error
✓ 60.1s
py 3.9
✕ build_error
✕ timeout
4736MB installed
● package 4736MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

xp
import dora.xp as xp
Commonly aliased as 'xp' for brevity when defining grids and args.
main
import dora
dora
import dora
The top-level package provides entry points like `dora.main`.

This quickstart defines a simple `train_model` function that accepts a configuration dictionary. It then sets up a hyperparameter grid using `dora.xp.arg` and uses `dora.main` to launch multiple experiments, one for each combination in the grid. Dora automatically creates and manages experiment directories, passing configuration parameters and internal metadata (like `_xp_id` and `_xp_dir`) to your function.

import dora import dora.xp as xp import time import os from typing import Dict def train_model(config: Dict): """Simulates a training run with a given configuration.""" print(f"[Experiment {config.get('_xp_id', 'local')}] Running with config: {config}") # Simulate some work time.sleep(0.1) result = config["lr"] * config["batch_size"] print(f"[Experiment {config.get('_xp_id', 'local')}] Result: {result}") # Dora automatically saves results in the experiment directory xp_dir = config.get('_xp_dir') if xp_dir: os.makedirs(xp_dir, exist_ok=True) with open(os.path.join(xp_dir, 'metrics.json'), 'w') as f: import json json.dump({'loss': result, 'accuracy': 1 - result / 100}, f) return {"loss": result, "accuracy": 1 - result / 100} # Define the grid search parameters grid = [ xp.arg("lr", [0.01, 0.1, 1.0]), xp.arg("batch_size", [16, 32]) ] if __name__ == "__main__": print("Launching Dora experiments...") # dora.main is the recommended way to launch experiments # It will iterate through the grid, call train_model for each configuration, # and manage experiment directories and logs. dora.main(train_model, grid=grid) print("Dora experiments finished.")
dora --version
Debug
Known issues
gotchaThe `xp.run()` function is primarily for quick local testing and does not fully leverage Dora's experiment management capabilities (like structured output directories, reproducibility, or distributed launching). For full features and robust experiment tracking, `dora.main()` is the recommended entry point.
fix
Always use `dora.main(your_experiment_function, grid=your_grid)` for production-grade experiment launches and grid searches.
affects: All v0.1.x
gotchaThe experiment function passed to `dora.main` (or `xp.run`) must accept exactly one argument, which will be a dictionary containing the current experiment's configuration, including Dora's internal parameters (e.g., `_xp_id`, `_xp_dir`).
fix
Ensure your experiment entry point is defined with a single dictionary argument, e.g., `def my_experiment_func(config: Dict): ...`.
affects: All v0.1.x
gotchaWhile Dora manages experiment parameters and results, it does not automatically manage the specific Python environment (dependencies, versions) used by your experiment code. Reproducibility often depends on consistent external environments.
fix
Use external tools like `conda`, `virtualenv`, `poetry`, or Docker to containerize and manage your experiment's dependencies for true reproducibility. Document your environment carefully.
affects: All v0.1.x
gotchaDora uses configuration keys prefixed with an underscore (e.g., `_xp_dir`, `_xp_id`) for its internal parameters. Defining your own grid arguments with keys starting with `_` can lead to conflicts or unexpected behavior.
fix
Avoid using keys that start with an underscore (`_`) in your custom grid definitions to prevent clashes with Dora's internal parameters.
affects: All v0.1.x
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dora'
This error occurs when the 'dora' package, or its submodules like 'dora.explore' or 'dora.log', is not found in the Python environment, often because `dora-search` was not installed or a dependency requiring it was not fully met.
fix
Install the `dora-search` package using pip: `pip install dora-search`.
ImportError: cannot import name 'hydra_main' from 'dora'
This specific import error arises when attempting to import `hydra_main` from the `dora` package, particularly noted in environments like Colab or Kaggle, indicating either a version mismatch or an architectural incompatibility in those specific environments.
fix
Ensure `dora-search` is updated (`pip install -U dora-search`) and check the `dora-search` GitHub issues for version-specific guidance related to `hydra` integration, or consider alternative experiment setup if running in constrained notebook environments.
FATAL: Could not find a training package. Use -P, or set DORA_PACKAGE to set the package.
This error means that when running a `dora` command (e.g., `dora run` or `dora grid`), the system could not locate the Python package containing your experiment's training module.
fix
Specify the training package using the `-P` flag (e.g., `dora run -P my_package`) or set the `DORA_PACKAGE` environment variable to the name of your package.
dora: command not found
This shell error indicates that the `dora` command-line utility is not recognized by your system's PATH, usually because `dora-search` was not installed correctly or its scripts directory is not in your system's executable path.
fix
Ensure `dora-search` is installed in your active Python environment (`pip install dora-search`) and that your shell's PATH includes the directory where pip installs scripts (e.g., `~/.local/bin` or a virtual environment's `bin`/`Scripts` folder).
Upgrade
Version history
0.1.12latest on PyPI · released May 23, 2023
Audit
Dependencies

No dependency data recorded yet.

Agent activity
16 hits · last 30 days
node
14
OpenAI (training)
1
Resources
dora-search — pip install dora-search · libregistry