Link Search Menu Expand Document

OpenDSS Installation for use in CLI

OpenDSS functionality is available through the URBANopt DiTTo Reader, which:

  • converts URBANopt output files for a scenario into OpenDSS input files
  • runs the OpenDSS workflow
  • stores OpenDSS results into the URBANopt scenario directory


While most of the URBANopt SDK uses Ruby, the OpenDSS part of the workflow is implemented in Python, and as such, has a different set of dependencies that must be installed:

  • Git
  • Python 3.7 or higher
  • Pip
  • Various python packages (, ditto)


  1. Ensure that you have python version 3.7 or higher installed on your system.

    Attention Pyenv users: You must install python with the ‘enable-shared’ flag:

     env PYTHON_CONFIGURE_OPTS='--enable-shared' pyenv install 3.7.X 
  2. Install pip. The following command should return the version if pip is already installed, and fail otherwise:
     pip --version
  3. Clone the urbanopt-ditto-reader to your local machine. Example:
     git clone
  4. Open a terminal in the cloned ditto-reader directory and install the ditto-reader dependencies:
     pip install -e .

    This command will also automatically clone the ditto repository to the following location: urbanopt-ditto-reader/ditto.

To verify your install, list the packages installed using the pip list command. The listing of packages installed should include UrbanoptDittoReader.

$ pip list
Package             Version Location
------------------- ------- ------------------------------------------
networkx            2.4
numpy               1.19.1    0.5.0
pandas              1.1.0
pip                 19.2.3
setuptools          41.2.0
traitlets           4.3.3
UrbanoptDittoReader 0.2.0   <path/to/urbanopt-ditto-reader>

Troubleshooting for WINDOWS users

Configuring the following environment variables may help if you are having issues running this workflow.

  • Ensure that the python directory and the python/Scripts directory are in your PATH variable
  • Ensure that the python paths from above are listed before the path that starts with %USERPROFILE% and points to AppData\Local\Microsoft\WindowsApps
  • Add an environment variable PYTHONPATH that points to your python directory
          PYTHONPATH = C:\Users\<username>\AppData\Local\Programs\Python\Python37
  • Add an environment variable LIBPYTHON that points to your python DLL
          LIBPYTHON = C:\Users\<username>\AppData\Local\Programs\Python\Python37\python37.dll

Once you have made these changes, close and reopen your Terminal/GitBash window for these changes to take effect.

Note that if you are not able to run the opendss command via the CLI, you can always access it manually by following the general OpenDSS instructions.


The DiTTo-Reader/OpenDSS workflow is available via the opendss URBANopt CLI command.


  • The run and process --default (post-process with the default post-processor) commands must first be run on a scenario to generate the input files required by OpenDSS.
  • The feature file should contain Electrical Connectors and Junctions for a successful OpenDSS run.
  • The location of ditto is assumed to be found at urbanopt-ditto-reader/ditto.
  • The equipment file is assumed to be at urbanopt-ditto-reader/example/electrical-database.json unless otherwise specified with the –equipment flag when issuing the command
  • If you want to include reopt results as an input to OpenDSS, make sure to specify the –reopt flag when issuing the command
  • Once the opendss command has been run, the process --opendss command can then be run to pull the opendss results back into the URBANopt reports.

For usage help:

uo opendss --help

An example:

  1. Create and run your project as you normal would, following the usage examples.

  2. Post-process using the default post-processor to generate the feature_reports used by the OpenDSS workflow:
     uo process --default --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>
  3. Use the opendss command to run the opendss workflow:
     uo opendss --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>
  4. Post-process using the opendss post-processor to integrate the opendss results into the feature_reports:
     uo process --opendss --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

URBANopt, Copyright (c) 2019-2020, Alliance for Sustainable Energy, LLC, and other contributors. All rights reserved.