Installation

CityLearn v3 is distributed as citylearn on PyPI and requires Python 3.9 or newer. Use a virtual environment to keep its dependencies separate.

python -m venv .venv

Activate it on Linux or macOS:

source .venv/bin/activate

On Windows PowerShell:

.venv\Scripts\Activate.ps1

Install and check the package:

python -m pip install --upgrade pip
python -m pip install citylearn
python -c "from citylearn import __version__; print(__version__)"

Continue with Your first simulation. Both the package and Python import name are citylearn.

Optional dependencies

For Parquet datasets or exports:

python -m pip install "citylearn[parquet]"

For PV autosizing from EPW weather using PySAM:

python -m pip install "citylearn[pysam]"

Datasets

Public datasets are downloaded from the official repository and cached locally. The first download needs internet access. List the available names in Python:

from citylearn.data import DataSet
print(DataSet().get_dataset_names())

For your own data, pass a local schema.json path instead of a dataset name. See Dataset Reference for files, units and offline use.

Existing projects and development

Record the installed version with the command above and pin that version in your project dependencies. Read Moving an existing project to CityLearn v3 when updating a project. To work on CityLearn itself, follow Developer Guide.