Upgrading Existing Deployments

It is often recommended that users upgrade to the latest stable release of VOLTTRON for their deployments. Major releases include helpful new features, bug fixes, and other improvements. Please see the guides below for upgrading your existing deployment to the latest version.


VOLTTRON 8 introduces three changes that require an explict upgrade step when upgrading from a earlier VOLTTRON version

  1. Dynamic RPC authorization feature - This requires a modification to the auth file. If you have a pre-existing instance of VOLTTRON running on an older version, the auth file will need to be updated.

  2. Historian agents now store the cache database (backup.sqlite file) in <volttron home>/agents/<agent uuid>/<agentname-version>/<agentname-version>.agent-data directory instead of <volttron home>/agents/<agent uuid>/<agentname-version> directory. In future all core agents will write data only to the <agentname-version>.agent-data subdirectory. This is because vctl install –force backs up and restores only the contents of this directory.

  3. SQLHistorians (historian version 4.0.0 and above) now use a new database schema where metadata is stored in topics table instead of separate metadata table. SQLHistorians with version >= 4.0.0 can work with existing database with older schema however the historian agent code should be upgraded to newer version (>=4.0.0) to run with VOLTTRON 8 core.

  4. VOLTTRON feature to run individual agents as unique Unix users is now named “agent-isolation-mode” and is consistently referred to using this name in code, configuration, and documentation. Before VOLTTRON 8.2 this configuration parameter was called “secure-agent-users” and related documentation referred to this mode as “secure mode”.

To upgrade:

  1. If upgrading historian, make sure historians are not in auto start mode. To remove any historian from auto start mode use the command ‘vctl disable <uuid of historian that is currently enabled>. This is necessary so that the old sqlhistorian does not automatically start after step 5.

  2. Update volttron source code version to VOLTTRON 8

  3. activate the volttron environment, and run `python bootstrap.py --force`. If you have any additional bootstrap options that you need (rabbitmq, web, drivers, etc.) include these in the above command.

  4. Run `volttron-upgrade` to update the auth file, move historian cache files into agent-data directory, and rename the config parameter “secure-agent-users” in VOLTTRON_HOME/config to “agent-isolation-mode” Note that the upgrade script will only move the backup.sqlite file and will not move sqlite historian’s db file if they are within the install directory. If using a SQLite historian, please backup the database file of sqlite historian before upgrading to the latest historian version.

  5. Start VOLTTRON

  6. Run `vctl install --force --vip-identity <vip id of existing historian> --agent-config <config>` to upgrade to the latest historian version. vctl install –force will backup the cache in <agent-version>.agent-data folder, installs the latest version of the historian and restore the contents of <agent-version>.agent-data folder.

Upgrading aggregate historians

VOLTTRON 8 also comes with updated SQL aggregate historian schema. However, there is no automated upgrade path for aggregate historian. To upgrade an existing aggregate historian please refer to the CHANGELOG.md within SQLAggregateHistorian source directory


VOLTTRON 7 includes a migration from Python 2.7 to Python 3.6, as well as security features, new agents, and more.

From 6.x

From version 6.x to 7.x important changes have been made to the virtual environment as well as VOLTTRON_HOME. Take the following steps to upgrade:


The following instructions are for debian based Linux distributions (including Ubuntu and Linux Mint). For Red Hat, Arch or other distributions, please use the corresponding package manager and commands.

  1. Install the VOLTTRON dependencies using the following command:

    sudo apt install python3-dev python3-venv libffi-dev


    This assumes you have existing 6.x dependencies installed. If you’re unsure, refer to the platform installation instructions.

  2. Remove your existing virtual environment and run the bootstrap process.

    To remove the virtual environment, change directory to the VOLTTRON project root and run the rm command with the -r option.

    rm -r env

    Now you can use the included bootstrap.py script to set up the new virtual environment. For information on how to install dependencies for VOLTTRON integrations, run the script with the --help option.

    python3 bootstrap.py <options>


    Because the new environment uses a different version of Python, using the --force option with bootstrap will throw errors. Please follow the above instructions when upgrading.

  3. Make necessary VOLTTRON_HOME changes


    It is possible that some existing agents may continue to operate after the platform upgrade, however this is not true for most agents, and it is recommended to reinstall the agent to ensure the agent wheel is compatible and that there are no side-effects.

    1. Reinstall Agents

    It is recommended to reinstall all agents that exist on the platform to ensure the agent wheel is compatible with Python3 VOLTTRON. In many cases, the configurations for version 7.x are backwards compatible with 6.x, requiring no additional changes from the user. For information on individual agent configs, please read through that agent’s documentation.

    1. Modify Agent Directories


    Modifying the agent directories is only necessary if not reinstalling agents.

    To satisfy the security requirements of the secure agents feature included with VOLTTRON 7, changes have been made to the agent directory structure.

    1. Keystore.json

    The agent keystore file has been moved from the agent’s agent-data directory to the agent’s dist-info directory. To move the file, change directory to the agents install directory and use the mv command.

    cd $VOLTTRON_HOME/agents/<agent uuid>/<agent dir>
    mv <agent>agent.agent-data/keystore.json <agent>agent.dist-info/
    1. Historian Database

    Historians with a local database file have had their default location change do the data directory inside of the agent’s install directory. It is recommended to relocate the file from $VOLTTRON_HOME/data to the agent’s data directory. Alternatively, a path can be used if the user the agent is run as (the VOLTTRON user for deployments not using the secure agents feature) has read-write permissions for the file.

    mv $VOLTTRON_HOME/data/historian.sqlite $VOLTTRON_HOME/agents/<agent uuid>/<agent>/data


    If not specifying a path to the database, the database will be created in the agent’s data directory. This is important if removing or uninstalling the historian as the database file will be removed when the agent dir is cleaned up. Copy the database file to a temporary directory, reinstall the agent, and move the database file back to the agent’s data directory

  4. Forward Historian

    For deployments which are passing data from 6.x VOLTTRON to the latest 7.x release, some users will experience timeout issues with the Forward Historian. By updating the 6.x deployment to the latest from the releases/6.x branch, and restarting the platform and forwarder, this issue can be resolved.

    . env/bin/activate
    git pull
    git checkout releases/6.x
    vctl start <forward id or tag>