To run URBANopt, first install the project dependencies and the URBANopt Command Line Interface.

Once the CLI is installed, help is available by typing uo -h from the command line.

  1. Create a project folder in your current directory using:


    This creates a project folder containing the example project, and downloads related weather files and detailed models to the appropriate folders.

    Alternatively, create an empty base project folder by using:


    This creates project folder without an example FeatureFile and an empty weather folder. You can download weather files and add to this folder from

  2. Put your FeatureFile in the root of the folder you just created, or use the provided example.
  3. For all following commands you must be inside the project directory you created in step 1.
  4. Create ScenarioFiles for all Features in the FeatureFile based off the example mappers using:

     uo -m -f <FEATUREFILE>

    Or create ScenarioFiles for a single Feature by specifying the Feature ID in the arguments.

     uo -m -f <FEATUREFILE> -i <FEATURE ID>

    You may write your own mapper file for your own specific use case as needed, as well as make your own ScenarioFile by hand. You may also make edits to the ScenarioFiles to mix and match mappers.

  5. Simulate energy usage of each feature or for a single Feature by specifying the appropriate ScenarioFile by using:


    Note that there is a runner.conf file automatically created in the project folder. This file is used to configure the number of features to process in parallel as well as a few other parameters. Make edits to this file prior to running the above command.

  6. Aggregate simulated features into a Scenario report by using:

  7. Delete an outdated Scenario run by using:

     uo -d -s <SCENARIOFILE>

Workflow Details

The figure below describes the workflow that takes place for the run and post_process calls.


The following figure represents how Simulation Mapper Classes can be assigned to different Features from the FeatureFile in the Scenario CSV.