Installation

Brightway is a Python software package. A user interface is available, but not necessary for use. Brightway can be installed using the Python package installer pip or the multi-language package management system conda and its friend mamba.

Note

Brightway supports Python >=3.8. This guide is for the current stable Brightway release (2.5); Activity-browser users should use the legacy Brightway 2 version Basic. See the difference between brightway2 and brightway 25.

Installing Brightway using pip

Linux, Windows, or MacOS (x64)

1. Install python from the website, your system package manager, or Homebrew.

2. Create a directory for your virtual environments, such as C:/Users/me/virtualenvs/

3. In a console or terminal window, create a new virtual environment. Note that command must be executed in parent directory of your virtual environments directory, e.g. C:/Users/me/ in our example above:

python -m venv virtualenvs/brightway

4. Activate the virtual environment. The exact syntax depends on your operating system; it will look something like:

source virtualenvs/brightway/bin/activate

5. Install Brightway:

pip install brightway25 pypardiso

6. (Optional) You can also use pip to install useful libraries like jupyterlab.

MacOS (Apple Silicon/ARM)

Note

If you are a beginner it’s easier to install Brightway via conda on Apple Silicon.

1. Install Homebrew.

2. Install python from Homebrew.

3. Install dependencies in a terminal window:

brew install swig suite-sparse

4. Create a directory for your virtual environments. This can be anywhere; we will use the home directory here as an example:

cd
mkdir virtualenvs

5. Create and activate a virtualenv:

python -m venv virtualenvs/brightway
source virtualenvs/brightway/bin/activate

Note: You might need to specify the python version, like python3.11.

6. Create a configuration file to help scikit-umfpack build correctly. This can be called anything (with a .ini extension); we will use custom-config.ini. Add the following to that file:

[properties]
umfpack-libdir = '/opt/homebrew/Cellar/suite-sparse/7.6.0/lib/'
umfpack-includedir = '/opt/homebrew/Cellar/suite-sparse/7.6.0/include/suitesparse/'

7. Install scikit-umfpack:

pip install scikit-umfpack -Csetup-args=--native-file=$PWD/custom-config.ini

This assumes that the custom-config.ini file is in your current working directory.

8. Install Brightway:

pip install brightway25 pypardiso

9. (Optional) You can also use pip to install useful libraries like jupyterlab.

Installing Brightway using conda or mamba

Prerequisites

1. A working installation of conda or mamba. If you are using conda, we recommend installing the libmamba solver.

2. Basic knowledge of Conda environments

Linux, Windows, or MacOS (x64)

1. Create a new Conda environment (in this example named brightway):

conda create -n brightway -c conda-forge -c cmutel brightway25

2. Activate the environment:

conda activate brightway

3. (Optional but recommended) You can also use conda to install useful libraries like jupyterlab:

conda install -c conda-forge jupyterlab

macOS (Apple Silicon/ARM)

Note

Brightway runs on the new Apple Silicon ARM architecture. However, the super-fast linear algebra software library pypardiso is not compatible with the ARM processor architecture. To avoid critical errors during instruction that would break core functionality, a different version of Brightway (brightway_nosolver) and a a different linear algebra software library (scikit-umfpack) must be installed.

1. Create a new Conda environment (in this example named brightway):

conda create -n brightway -c conda-forge -c cmutel brightway25_nosolver scikit-umfpack

2. Activate the environment:

conda activate brightway

3. (Optional but recommended) You can also use conda to install useful libraries like jupyterlab:

conda install -c conda-forge jupyterlab

Updating Brightway

Brightway is being actively developed, with frequent new releases. To update Brightway using pip, activate your virtual environment, and run:

pip install -U brightway25

To update Brightway using conda or mamba, activate your environment, and run:

conda update -c conda-forge -c cmutel brightway25

Warning

Apple Silicon users should update brightway25_nosolver.

Warning

Newer versions of Brightway can introduce breaking changes. We recommend you create a new environment for each project, and only update Brightway when you are ready to update your project.