Generic installation instructions

Brightway2 can be installed pretty much everywhere, on Windows, OS X, Linux, and anywhere else Python can be compiled.

Python 2 or 3

Brightway2 supports python 2 and 3, but the recommended version is python 3.5. Tests are run against 2.7, 3.4 and 3.5. Python 3 versions less than 3.4 are not supported.

The library eight is used to forward-port python 2.7 code to 3.X. This means that super, str, and bytes have 3.X semantics. The print function and true division are imported from __future__, as are unicode_literals.

See also:

Note

Please subscribe to the brightway2 updates mailing list to be informed of new releases.

Notebook directory

It is best practice to store your notebooks in a different directory outside of the bw2-python directory - and probably separate directories for each project you are working on. One reasonable place would be in your Documents or Desktop. You can safely copy the notebooks script to this other directory (or directories).

Cloud installs

Brightway2 is designed to run without too much fuss on servers in the cloud. See the instructions for using Docker and specific instructions for Cloud Nine.

Building from source: Continuum Miniconda

The easiest way to get started is to download Miniconda. This is a reduced version of the entire Anaconda suite - we will download the libraries we need.

  1. Save Miniconda 3.5 (64-bit version) for your OS

On Mac OS X, you might have to make the bash script executable:

chmod +x ~/Downloads/Miniconda3-latest-MacOSX-x86_64.sh

(or whatever version you have; you might need to adjust the path as well)

  1. Run the Miniconda installer.

Windows

Double click the installer file Miniconda3-latest-Windows-x86_64.exe.

Install just for yourself:

_images/windows-1.png

Next, change the default installation location to C:\bw2-python:

_images/windows-2.png

We generally recommend against making this your default Python:

_images/windows-3.png

Finally, open a command line shell by searching for cmd.exe in the start menu:

_images/windows-4.png

OS X/Linux

Run Miniconda3-latest-MacOSX-x86_64.sh (or equivalent) to start the Miniconda installer:

_images/osx-1.png

Press enter to start reading the Miniconda license.

_images/osx-2.png

Press the space bar to go through the license.

_images/osx-3.png

Type yes to agree to the license terms. Next, change the default installation location to /Users/<your user name>/bw2-python (OS X) or /home/<your user name>/bw2-python/ (Linux). You don’t have to use the directory name bw2-python, but if you change this than be sure to adapt the following commands.

Warning

You can’t easily move this directory later, as its path is hard-coded in many files. If you make a mistake, it is better to start the installation from the beginning.

If you don’t have another copy of Python on your machine, then you can make this your default Python interpreter. However, it will also work just fine if you don’t make it your default Python - you will just need to type a bit more to activate this Python version each time you start a terminal or command shell. If you don’t want to make it your default python, then you will need to adjust the paths so that the following commands work. For example, instead of running conda, you will probably need to change to the correct directory first, e.g. something like cd ~/bw2-python/bin/.

_images/osx-4.png
  1. If you didn’t make this your default Python, change to the right directory in the same terminal window or command shell:
  • Windows: cd C:\bw2-python\Scripts\
  • Otherwise: cd ~/bw2-python/bin
  1. In the same terminal window or command prompt, make sure conda is up to date:
conda install -q -y conda && conda update -q conda

Note

On OS X/Linux, you might have to use ./conda instead of conda.

Note

To paste in a command Windows, use a right click of the mouse.

  1. Add the conda-forge channel, which has additional and updated packages:
conda config --system --add channels conda-forge
  1. Create a python environ for brightway2:
conda create -y -n bw2 python=3.5
  1. Activate your environment using one of the following:

Windows:

activate bw2

Otherwise:

source activate bw2

You will have to activate your brightway2 environment in each new terminal window or command shell using a command like source ~/bw2-python/bin/activate bw2 (adjust for the path you chose) before running IPython or the Jupyter notebook server.

6b. Then change out of your current directory to avoid conflicts:

cd ..
  1. Install or update some dependencies. We will first update the tools for installation (pip, setuptools, wheel). Then, we install an awesome wrapper by Adrian Haas of the Pardiso solver provided in the Intel MKL library. Finally, we install some dependencies for Brightway2. Each of these commands should be run on a separate line:
conda install wheel && conda update -q pip wheel setuptools
conda install -q -y -c haasad pypardiso
conda install -q -y ipython ipython-notebook jupyter matplotlib flask lxml requests nose docopt whoosh xlsxwriter xlrd unidecode appdirs future psutil unicodecsv wrapt

7a. If you are on Windows, you also need to do:

conda install -q -y pywin32
  1. If you are on Linux (or really anything other than OS X or Windows), you will need a C compiler to build the backage bw2speedups. This should be provided by your distribution in something like build-essentials or build-essential.
  2. Finally, install the development version of brightway2:
pip install --no-cache-dir brightway2

You can now use brightway2 from the python shell or in an ipython notebook.

  1. After installing all packages, you can save some disk space by cleaning conda:
conda clean -tipsy

You can download OS X scripts to start both IPython and the Jupyter notebook server (see also scripts for Windows). These scripts can be run in the Terminal, or from the Finder, if you associate them with the Terminal app. These scripts assume you installed into the default path, but can easily be edited to adjust paths.

Activity-browser

_images/activity-browser.png

The activity browser is an experimental graphical user interface for Brightway2.

To install:

conda install networkx seaborn matplotlib
pip install https://bitbucket.org/cmutel/activity-browser/get/2.0.zip

You can now run the activity browser with the command:

activity-browser

Alternatives

Windows

Although Brightway2 is relatively simple, installation of the numerical and scientific libraries can be difficult as there is no default compilers installed on most Windows machines. This issue is well-known in the Python community (see Pycon keynote, recent reddit discussion). The only sensible way is to use a precompiled set of packages.

In addition to conda, the following also work well, but no specific instructions are provided:

Enthought Canopy

Warning

Canopy Express will not work with Brightway2, as it does not include the lxml package.

Enthought Canopy provides a nice Python environment and free academic licenses.

Python(x,y)

Download and install the Python(x,y) executable. All the necessary background libraries will be installed.

Winpython

Winpython is another set of Windows Python packages, similar to Python(x,y). I haven’t tried this, but have heard good things. I think you will have to use either easy_install or Christoph Gohlke’s Windows binaries to install lxml.

Max OS X

On OS X, there are almost too many choices that work well. The simplest way is to use Enthought Canopy or Building from source: Continuum Miniconda - the instructions are the same as on Windows. Alternatively, there are two main OS X-specific alternatives for installing Python packages: Macports and Homebrew. Brightway2 is developed primarily on OS X using Macports, but as it depends on a few standard libraries, either alternative should work well. Homebrew users will have to adapt the following instructions, but reports are that this is relatively simple.

Note

See also the Quickstart for OS X developers notes for an even more powerful & complicated approach, good for software developers.

Follow the instructions and install Macports. Note that both Macports and Homebrew require Xcode to be installed first. Xcode can be installed from the OS X installation disk (for 10.6 or lower), the app store (10.7 or higher), or other unofficial sources.

Next, install the needed Python libraries using this command in the Terminal:

sudo port install python_select py35-scipy py35-numpy py35-pip py35-libxml2 py35-nose py35-sphinx py35-requests py35-flask

Point to the correct Python executable:

sudo port select --set python python35

Next, install the Brightway2 source code using another Terminal command:

pip-3.5 install --user brightway2

Unfortunately, the Brightway2 scripts aren’t in our PATH environment variable yet. Fix this by adding the following line to the end of the .profile file in your home directory, and then start a new terminal window:

export PATH=$PATH:/opt/local/Library/Frameworks/Python.framework/Versions/3.5/bin

Linux

General instructions are provided for Ubuntu 14.04; people using other distributions are assumed smart to be enough to adapt as necessary.

First, install the required apt packages. You can select them in the graphical interface, or through one command in the terminal:

sudo apt-get update
sudo apt-get install python-scipy python-numpy python-nose python-pip python-lxml cython python-virtualenv virtualenvwrapper build-essential libsuitesparse-dev swig

Next, logout and login again, and create a new virtualenv:

mkvirtualenv bw2
toggleglobalsitepackages

Next, install Brightway2 using another terminal command:

pip install -U pip wheel setuptools
pip install eight bw2speedups scikit-umfpack
pip install --user brightway2

Developers

Warning

If you are developing, it is strongly recommended to use virtualenv and virtualenvwrapper (or virtualenv-win for Windows users).

If you want to develop with Brightway, then you should also install the following:

  • py.test
  • sphinx

You can install editable Brightway2 packages using mercurial:

pip install -e hg+https://bitbucket.org/cmutel/brightway2-data#egg=bw2data
pip install -e hg+https://bitbucket.org/cmutel/brightway2-calc#egg=bw2calc
pip install -e hg+https://bitbucket.org/cmutel/brightway2-ui#egg=bw2ui
pip install -e hg+https://bitbucket.org/cmutel/brightway2-analyzer#egg=bw2analyzer

You can also simply clone the bitbucket source code repositories instead of installing them.

Quickstart for OS X developers

Set up python:

sudo port selfupdate
sudo port install py35-scipy py35-numpy py35-pip py35-libxml2 py35-nose py35-sphinx py35-requests py35-flask py35-virtualenvwrapper mercurial +bash_completion
sudo port select --set python python35
sudo port select --set pip pip35
sudo port select --set virtualenv virtualenv35

Change the shell to macports bash. First, add the macports bash shell as a possibility:

sudo -s
# Type in your password here
echo /opt/local/bin/bash >> /etc/shells
exit

Then set your default shell

chsh -s /opt/local/bin/bash

Add the following lines to the file .profile in your home directory using your favorite text editor:

source /opt/local/Library/Frameworks/Python.framework/Versions/3.4/bin/virtualenvwrapper.sh

if [ -f /opt/local/etc/profile.d/bash_completion.sh ]; then
  . /opt/local/etc/profile.d/bash_completion.sh
fi

You must then start a new terminal window, so the updated .profile is applied.

Create a virtualenv and install Brightway2:

mkvirtualenv bw2
toggleglobalsitepackages
pip install brightway2

Because this is using a virtualenv, you will need to activate the virtualenv each time you start a new terminal with:

workon bw2

Upgrading Brightway2

Brightway2 is being actively developed, and new releases come frequently.

Note

Please subscribe to the brightway2 updates mailing list to be informed of new releases.

To upgrade Brightway2, do the following:

First, make sure your background packages are up to date.

  • In Enthought Canopy, this is done through the graphical package manager.
  • In anaconda/miniconda, use the following commands (once you have activated your Brightway2 environment):
conda update conda
conda update anaconda
  • In macports, use the following commands:
sudo port selfupdate
sudo port upgrade outdated

Next, run the following command. Make sure you are in the correct environment/virtualenv, if you use environments:

pip install -U --no-deps brightway2 bw2data bw2calc bw2analyzer bw2ui bw2io bw2parameters

Brightway2 Packages

Brightway2 is split into several packages, where each package fulfills a certain role in the framework. The idea is that you can be an expert on a certain package, but not have to learn anything about other packages.

Core packages

brightway2

This manual, plus a generic container that imports from brightway2-data and brightway2-calc.

brightway2-data

This package provides facilities for managing LCI databases and LCIA methods, as well as input and output scripts.

brightway2-calc

This package provides classes for LCA calculations, both static and uncertain, and basic regionalized LCA.

brightway2-analyzer

This package provides functions for interpreting and analyzing LCI databases, LCIA methods, and LCA results.

Secondary packages

These packages are extensions to Brightway2, and have lower standards for documentation and test coverage. They show how Brightway2 can be extended into new areas of LCA.

brightway2-regional

Full-fledged regionalization in Brightway2.

brightway2-temporalis

Dynamic LCA in Brightway2.