This section describes how to adapt a user script with Oríon. To customize how Oríon parses the commandline or execution environment see Orion customization. If the user script requires information about the running trial, such as its id, the working directory or the experiment’s name, look at Command-line templating or Environment variables.

Orion customization


By default Oríon will only consider the file passed through the argument --config as a configuration file for the user script. However, it is possible to change the default argument inside the global configuration file of Oríon through the user_script_config argument, like this:

    user_script_config: configuration

It is then possible to run orion hunt like here:

orion hunt --config my_orion_config.yaml ./my_script --configuration my_script_config.txt

As you can see, the configuration file for the user script is now passed through --configuration. This should not be confused with the argument --config of orion hunt, which is the configuration of Oríon. We are here referring the configuration of the user script, represented with my_script_config.txt in the previous example.


By default the working directory where trial configuration scripts are saved will be a temporary folder that is deleted at end of execution of the trial. To keep the data in a particular folder, you can specify --working-dir or define it in the configuration file, either the global one or the local one passed to hunt --config <file_path>. This working directory is where all trial directories will be created. To access the particular working directory of a trial, see next sections Command-line templating and Environment variables.

Language compatibility

The command line works for scripts and programs in any language. The only requirement is that the executed script returns a JSON string with the objective value.

The format is

      "name": "some-objective",
      "type": "objective",
      "value": 1

See orion.client.report_results() for more details.

Command-line templating

When parsing the commandline of the experiment to execute a trial, Oríon will replace any templates referencing the experiment or the trial. This means that execution of the following line

orion hunt [...] ./my_script [...] --dir '{trial.working_dir}'

would replace {trial.working_dir} with the actual path of the trial’s working dir. Since it is using templating, you can place the templates wherever you want including formats such as

orion hunt [...] ./my_script [...] --some-arg some-weird-{}-{}-value

Here is a list of convenient attributes of the Experiment and Trial objects which are available through templates.



ID of the experiment

Name of the experiment


Version of the experiment


Global working dir of the experiment

Unique ID of the trial


Deprecated. Unique ID of the trial prior to v0.2.5.


Working dir of the trial


md5sum hash for the parameters (w/o fidelity)


Templates are only supported in commandline and not in user script configuration at the moment. We plan to support both in the future. Contributions are very welcome. :)

Environment variables

When executing the trial, Oríon will set local environment variables available to the user script. We list them below.


Current experiment that is being ran.


Name of the experiment the worker is currently working on.


Version of the experiment the worker is currently working on.


Current trial id that is currently being executed in this process.


Deprecated. Unique ID of the trial prior to v0.2.5.


Trial’s current working directory.


Trial’s results file that is read by the legacy protocol to get the results of the trial after a successful run.