Skip to content

Installation

bw_timex is a Python software package. It's available via pip and conda / mamba.

Note

bw_timex depends on Brightway25, and will install bw25-compatible versions of the bw packages. This means that it cannot be added to existing environments that are based on Brightway2, e.g., environments containing Activity Browser.

Installing bw_timex using uv

uv is a fast, modern Python package manager written in Rust. It's significantly faster than pip and handles dependency resolution more reliably. Installing uv is a one-liner.

Create a new project with uv:

uv init my-timex-project
cd my-timex-project
uv add bw_timex

Run your scripts with:

uv run python my_script.py

Or directly get started in JupyterLab:

uv run --with jupyter jupyter lab

By default, jupyter lab will start the server at http://localhost:8888/lab.

Create and activate a new virtual environment:

uv venv .venv
source .venv/bin/activate  # Linux/macOS
# or: .venv\Scripts\activate  # Windows

Install bw_timex:

uv pip install bw_timex

If you already have an activated virtual environment:

uv pip install bw_timex

Note

Fast calculations on macOS need SuiteSparse. uv manages your Python environment, but this system-level library has to come from Homebrew first.

Install system dependencies:

brew install swig suite-sparse

uv init my-timex-project
cd my-timex-project
uv add "bw_timex[solvers]"

Run Jupyter (without adding it to the project):

uv run --with jupyter jupyter lab

uv venv .venv  # skip if reusing an existing environment
source .venv/bin/activate
uv pip install "bw_timex[solvers]"

Installing bw_timex using pip

  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:

    python -m venv C:/Users/me/virtualenvs/timex

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

    source C:/Users/me/virtualenvs/timex/bin/activate # Linux/macOS
# or: C:\Users\me\virtualenvs\timex\Scripts\activate # Windows

  5. Install bw_timex:

    pip install bw_timex

You can also use pip to install useful libraries like jupyterlab.

Note

Fast calculations on macOS need SuiteSparse. This background library can be installed via homebrew, as shown in this section, or via conda or mamba, as shown below.

  1. Install python from Homebrew.

  2. Install the requirements for SuiteSparse via homebrew:

    brew install swig suite-sparse

  3. In a terminal window, create a directory for your virtual environments. This can be anywhere; we will use the home directory here as an example:

    cd
mkdir virtualenvs

  4. Create and activate a virtualenv:

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

  5. Install bw_timex:

    pip install "bw_timex[solvers]"

You can also use pip to install useful libraries like jupyterlab.

Installing bw_timex 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

Note

bw_timex's conda package can't pin platform-specific run dependencies (it's built noarch), so pypardiso - the fastest linear algebra solver for lci() - isn't installed automatically. Add it yourself, as shown below.

  1. Create a new Conda environment with bw_timex:

    conda create -n timex -c conda-forge -c cmutel -c diepers bw_timex pypardiso

  2. Activate the environment:

    conda activate timex

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

    conda install -c conda-forge jupyterlab

Note

Brightway runs on macOS, but its default linear algebra library pypardiso does not. To avoid critical errors during installation that would break core functionality, a different version of Brightway (brightway_nosolver) and a different linear algebra library (scikit-umfpack) must be installed.

  1. Create a new Conda environment with bw_timex:

    conda create -n timex -c conda-forge -c cmutel -c diepers bw_timex brightway25_nosolver numpy">=2" scikit-umfpack">=0.4.2"

  2. Activate the environment:

    conda activate timex

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

    conda install -c conda-forge jupyterlab

Building background databases automatically

TimexLCA can build the prospective background databases a scenario names, using premise. That needs the optional extra:

pip install "bw_timex[premise]"

Install the extra in its own environment

premise requires numpy < 2, so installing this extra into an environment that already runs bw_timex downgrades numpy (and with it scipy) to the 1.x series rather than just adding a package (resolving the extra today gives numpy 1.26.4 and scipy 1.13.1). numpy 1.26.4 also ships wheels only up to CPython 3.12, so on Python 3.13 the install falls back to building numpy from source, which does not compile.

Give it a separate environment on Python 3.11 or 3.12:

uv venv --python 3.12 .venv-premise
source .venv-premise/bin/activate
uv pip install "bw_timex[premise]"

Brightway projects are shared between environments, so this costs you nothing but a second environment: build the vintages there (with bw_timex.ensure_scenario_databases, or a TimexLCA(..., create_missing=True) call), then run your actual calculations from your normal bw_timex environment against the same Brightway project - it will find the databases premise wrote by their metadata.

Building needs credentials, which bw_timex reads from the environment unless you pass them:

variable needed for
PREMISE_KEY decrypting premise's bundled IAM scenarios
ECOINVENT_USERNAME, ECOINVENT_PASSWORD importing ecoinvent, if the project has none yet