{"id":4938,"library":"dora-search","title":"Dora Search","description":"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.","status":"active","version":"0.1.12","language":"python","source_language":"en","source_url":"https://github.com/facebookresearch/dora","tags":["machine learning","hyperparameter tuning","experiment management","grid search","reproducibility","facebook research"],"install":[{"cmd":"pip install dora-search","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Commonly aliased as 'xp' for brevity when defining grids and args.","symbol":"xp","correct":"import dora.xp as xp"},{"symbol":"main","correct":"import dora"},{"note":"The top-level package provides entry points like `dora.main`.","symbol":"dora","correct":"import dora"}],"quickstart":{"code":"import dora\nimport dora.xp as xp\nimport time\nimport os\nfrom typing import Dict\n\ndef train_model(config: Dict):\n    \"\"\"Simulates a training run with a given configuration.\"\"\"\n    print(f\"[Experiment {config.get('_xp_id', 'local')}] Running with config: {config}\")\n    # Simulate some work\n    time.sleep(0.1)\n    result = config[\"lr\"] * config[\"batch_size\"]\n    print(f\"[Experiment {config.get('_xp_id', 'local')}] Result: {result}\")\n\n    # Dora automatically saves results in the experiment directory\n    xp_dir = config.get('_xp_dir')\n    if xp_dir:\n        os.makedirs(xp_dir, exist_ok=True)\n        with open(os.path.join(xp_dir, 'metrics.json'), 'w') as f:\n            import json\n            json.dump({'loss': result, 'accuracy': 1 - result / 100}, f)\n\n    return {\"loss\": result, \"accuracy\": 1 - result / 100}\n\n# Define the grid search parameters\ngrid = [\n    xp.arg(\"lr\", [0.01, 0.1, 1.0]),\n    xp.arg(\"batch_size\", [16, 32])\n]\n\nif __name__ == \"__main__\":\n    print(\"Launching Dora experiments...\")\n    # dora.main is the recommended way to launch experiments\n    # It will iterate through the grid, call train_model for each configuration,\n    # and manage experiment directories and logs.\n    dora.main(train_model, grid=grid)\n    print(\"Dora experiments finished.\")","lang":"python","description":"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."},"warnings":[{"fix":"Always use `dora.main(your_experiment_function, grid=your_grid)` for production-grade experiment launches and grid searches.","message":"The `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.","severity":"gotcha","affected_versions":"All v0.1.x"},{"fix":"Ensure your experiment entry point is defined with a single dictionary argument, e.g., `def my_experiment_func(config: Dict): ...`.","message":"The 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`).","severity":"gotcha","affected_versions":"All v0.1.x"},{"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.","message":"While 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.","severity":"gotcha","affected_versions":"All v0.1.x"},{"fix":"Avoid using keys that start with an underscore (`_`) in your custom grid definitions to prevent clashes with Dora's internal parameters.","message":"Dora 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.","severity":"gotcha","affected_versions":"All v0.1.x"}],"env_vars":null,"search_vec":"'0.1.12':38 'activ':42 'capabl':56 'current':35 'design':14 'develop':10,43 'dora':1,3 'ensur':33 'experi':7,29,52,61 'facebook':12,66 'focus':49 'frequent':46 'grid':17,63 'help':27 'hyperparamet':20,59 'launch':55 'learn':24,58 'log':30 'machin':23,57 'manag':8,62 'minor':47 'organ':28 'pace':44 'project':25 'reproduc':34,65 'research':13,67 'result':31 'robust':51 'search':2,4,18,64 'simplifi':16 'tool':9 'track':53 'tune':21,60 'updat':48 'version':37","created_at":"2026-04-12T16:47:08.440230+00:00","updated_at":"2026-04-16T14:41:05.082630+00:00","problems":[{"fix":"Install the `dora-search` package using pip: `pip install dora-search`.","cause":"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.","error":"ModuleNotFoundError: No module named 'dora'"},{"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.","cause":"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.","error":"ImportError: cannot import name 'hydra_main' from 'dora'"},{"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.","cause":"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.","error":"FATAL: Could not find a training package. Use -P, or set DORA_PACKAGE to set the package."},{"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).","cause":"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.","error":"dora: command not found"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.1.12","cli_name":"dora","cli_version":"","type":"library","homepage":null,"github":"https://github.com/facebookresearch/dora","docs":null,"changelog":null,"pypi":"https://pypi.org/project/dora-search/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}