plexos2duckdb

Important

This software is in beta pre-production. Interfaces, behavior, and data format may change without notice before the production release.

plexos2duckdb is a software tool to convert PLEXOS solution files to a DuckDB database.

Installation

Option 1: Install with uv (recommended)

On supported platforms, you can install the command-line tool directly from PyPI using uv:

uv add --prerelease=allow plexos2duckdb
# or
uv pip install --prerelease=allow plexos2duckdb

Then verify the install:

plexos2duckdb --version

Note that this requires a published wheel for your platform.

If you are interested just in the CLI, you can use uvx to install in an isolated environment:

$ uvx --prerelease=allow plexos2duckdb --help

A tool to convert PLEXOS Solution files to a DuckDB database.

Usage: plexos2duckdb <COMMAND>

Commands:
  convert                     Convert a PLEXOS solution file to DuckDB
  inspect                     Show operational metadata from a generated DuckDB database
  generate-shell-completions  Generate shell completion scripts
  help                        Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Option 2: Download pre-built binary

Pre-built binaries for the CLI are available from the GitHub Releases page.

1. Go to the latest release page on GitHub.

2. Download the appropriate binary for your operating system.

3. Extract the archive:

   tar -xzf plexos2duckdb-<platform>.tar.gz

   or on Windows:

   Expand-Archive plexos2duckdb-<platform>.zip -DestinationPath .

4. Copy the binary to a directory in your PATH, e.g.:

   # MacOS/Linux
   cp plexos2duckdb ~/local/bin/
   # Windows
   copy plexos2duckdb.exe %USERPROFILE%\local\bin\

   You will have to make sure ~/local/bin/ is in your PATH.

Quickstart

CLI usage

Note

The following assumes you have installed the CLI tool using one of the methods above and have plexos2duckdb in the PATH environment variable.

Verify installation is successful by checking the version:

plexos2duckdb --version

Run the help command to see available options:

plexos2duckdb --help

Convert a solution zip file to a duckdb database:

plexos2duckdb convert --input "Model-DayAhead-Solution.zip" --output "Model-DayAhead-Solution.duckdb"

If the output database already exists, re-run with --force to overwrite it:

plexos2duckdb convert --input "Model-DayAhead-Solution.zip" --output "Model-DayAhead-Solution.duckdb" --force

Inspect an existing database to view metadata, source file info, model name, and table inventory with row counts:

plexos2duckdb inspect --input "Model-DayAhead-Solution.duckdb"

Generate shell completions to stdout with the generate-shell-completions subcommand:

plexos2duckdb generate-shell-completions bash > ~/.local/share/bash-completion/completions/plexos2duckdb
plexos2duckdb generate-shell-completions zsh > ~/.zfunc/_plexos2duckdb

You may use any duckdb compatible database viewer to interactively explore the data with SQL:

Python usage

Import the PLEXOS2DuckDB class from the plexos2duckdb package, create a client instance with the path to your solution zip file, and call the convert() method to generate the DuckDB database.

You can also use the same client as a context manager to interact with the database connection directly.

from plexos2duckdb import PLEXOS2DuckDB

client = PLEXOS2DuckDB("./Model DAY_AHEAD Solution.zip")
output_path = client.convert() # "./Model DAY_AHEAD Solution.duckdb"

with client as db:
    # assumes output_path exists at "./Model DAY_AHEAD Solution.duckdb"
    print(db.connection.query("SELECT * FROM information_schema.tables"))