Installation#

Step 1. Clone GitHub Repository#

Users can clone the repository using HTTPS, SSH, or GitHub CLI. See GitHub docs for information on the different cloning methods. If you run into issues, follow GitHub troubleshooting suggestions here.

Using HTTPS#

git clone https://github.com/PyPSA/pypsa-usa.git

Using SSH-Key#

If it your first time cloning a repository through ssh, you will need to set up your git with an ssh-key by following these directions.

git clone git@github.com:PyPSA/pypsa-usa.git

Step 2. Initialize Configuration files#

From the command line, run the script init_pypsa_usa.sh to seed the per-user configuration files into the workflow/config folder.

Only three files are copied — config.default.yaml (a starting point for your own scenario config), config.api.yaml (API keys) and config.slurm.yaml (HPC account settings). Every other configuration file is read by the workflow directly from the tracked workflow/repo_data/config/ templates, so it can never fall out of sync with your checkout. The script is safe to re-run: existing files are left untouched.

bash init_pypsa_usa.sh

Step 3: Set-up Environment (mamba or UV)#

PyPSA-USA can be managed through either UV or mamba. Users only need to install one, not both!

PyPSA-USA requires Python 3.11 (>=3.11, <3.12). Core dependencies are pinned (pypsa==1.3.0, atlite==0.3.0, linopy==0.9.1, pandas==3.0.5), so please install from the lock files below rather than upgrading packages manually.

See also

If you are planning to develop PyPSA-USA, please see our contribution guidelines for installing additional dependencies.

Step 3a: uv installation#

UV is a new python package management tool from Astral, the creators of ruff. It replaces mamba, conda, and pip commands for one package and virtual environment management tool. Instructions for installing UV can be found here.

Once UV is installed, create the Python 3.11 environment, activate it, and install the pinned dependencies with:

uv venv --python 3.11
source .venv/bin/activate
uv sync

If Python 3.11 is not available on your system, UV can install it for you with uv python install 3.11. Prefixing commands with uv run (as shown on the usage page) also keeps the environment in sync automatically.

Warning

If you are migrating from mamba/conda, you may need to install system level dependencies that conda has previously handled. These include the HDF5 and GDAL>=3.1 libraries.

Step 3b: mamba Installation#

Alternatively, PyPSA-USA can manage project dependencies through conda/mamba. You can download and install mamba following the instructions. Follow links for mambaforge installation. There are two ways to install mamba, the first (recommended) method will start with a fresh install, meaning if you have previously installed conda environments, you will need to recreate these conda envs. If you already have conda installed and do not wish to install mamba, you can follow the same set of instructions replacing any mamba with conda

Once mamba is installed, use the environment file within the git repository to create the PyPSA-USA conda environment. This step can take ~10-20 minutes. After creating the mamba environment, you will need to activate it before running the snakemake workflow.

mamba env create -f workflow/envs/environment.yaml
mamba activate pypsa-usa

You also have the option to use miniconda. Download miniconda following their instructions.

Step 4: Install a Solver#

PyPSA-USA uses an external solver to solve the optimization problem formulated in the workflow. After you install your solver and confirm it is accessible within your conda environment, update your solving configuration to match your solver of choice. You can download and install several free options here:

and the non-free, commercial software (for some of which free academic licenses are available)

Note

config/config.default.yaml is set up for Gurobi (solving: solver: name: gurobi), and the example commands on the usage page pass --scheduler-ilp-solver GUROBI_CMD. If you do not have a Gurobi license, set solving: solver: name: highs in your configuration — the HiGHS python package (highspy) is already installed with the environment — and simply drop the --scheduler-ilp-solver GUROBI_CMD flag from your snakemake commands (it only configures Snakemake’s internal job scheduler, not the optimization solver).

Step 5 (optional): Get an EIA API Key#

A default power-only run does not need an EIA API key — conventional: dynamic_fuel_price: enable is false in config.default.yaml, and with it off the workflow makes no EIA request at all. The key is only needed for the parts of the workflow that read the EIA API directly:

  • dynamic fuel prices (conventional: dynamic_fuel_price: enable: true),

  • sector-coupled and AEO-scaled demand (build_demand with EIA/AEO scenarios),

  • trade cost lookups (imports/exports: costs: wholesale),

  • the historical-validation plots (plot_validation_*).

If you need any of those, you can quickly get a key by completing this form.

The API key will be emailed to you. Paste it into workflow/config/config.api.yaml, or export it as the EIA_API_KEY environment variable — the environment variable takes precedence over the YAML value, which keeps the key out of your files entirely.