Installation

[Git clone : pvgis] [Install via pip : pip install git+]

Requirements¶

• An operating system that supports Python < 3.12, >=3.11
• A C compiler such as gcc for building Python C extensions (required by xarray-extras)
• Noto fonts installed to ensure proper display of characters in CLI and documentation
• A virtual terminal that properly renders UTF-8 characters (e.g., Gnome Console)
• Python virtual environment tooling for isolated package installation
• The uv tool for fast and reliable installation management

Quick Start with uv¶

For the impatient, launch a terminal, navigate inside a local directory in your system and copy-paste-execute the following batch of commands to install PVGIS using uv in a dedicated environment :

git clone -b main https://code.europa.eu/pvgis/pvgis
cd pvgis
uv venv .pvgis_virtual_environment
source .pvgis_virtual_environment/bin/activate
uv pip install .
pvgis-prototype --version

Step-by-Step¶

Would you rather like to understand each step of the installation process ?

A safe and clean way to install pvgis is to clone the main branch of the source code and use uv to install it in an isolated environment :

1. Clone the source code¶

Next, clone the source code

# Inside some local directory in your system
git clone -b main https://code.europa.eu/pvgis/pvgis
cd pvgis

2. Create a virtual environment¶

Before installing PVGIS, create an isolated virtual environment to avoid polluting the system. In addition, removing a dedicated environment is easy and leaves no traces behind.

uv venv .pvgis_virtual_environment

3. Install PVGIS¶

Finally, install PVGIS via

source .pvgis_virtual_environment/bin/activate
uv pip install .

This will install the algorithms, the core API and the CLI components.

If you wish to install the Web API, then try :

uv pip install .[web]

4. Verify installation¶

pvgis-prototype --version

If the installation is successful, and with the virtual environment activated, we can use PVGIS commands !

pvgis-prototype --help

5. Deactivate the environment¶

Done working with PVGIS ? It is good practice to deactivate the virtual environment via :

deactivate

# Standard Python

## Environment setup

**Create a Python [virtual environment][venv]!**
and activate it :

``` bash
python -m venv pvgis-virtual-environment
source pvgis-virtual-environment/bin/activate

export PIP_REQUIRE_VIRTUALENV=true

pip install¶

Of course we can just use pip. Once inside a dedicated virtual environment -- see Python virtual environment -- we can install PVGIS with a single command using pip, Python's standard package installer :

$ pip install git+https://code.europa.eu/pvgis/pvgis
---> 100%
..
Building wheels for collected packages: pvgisprototype
Building wheel for pvgisprototype (pyproject.toml) ... done
Created wheel for pvgisprototype: filename=pvgisprototype-0.8.3-py3-none-any.whl size=32225753 sha256=3c658cf43ab6e7913bbacabd51344948e420b7b875a0fa7e174b00f9fc98a50e
Stored in directory: /tmp/pip-ephem-wheel-cache-ra_n3wre/wheels/a6/36/0f/97514dbae676105e1d4f6f9581498547b769a5fbd3afe74ca9
Successfully built pvgisprototype
..

For Developers¶

Are you a developer or a Power-User ? Curious to explore the latest (non-released development) version ? Want to modify some function or add a new one and contribute to PVGIS ? You can install PVIS in an editable mode.

pip install -e¶

1. Clone the source code repository

   $ git clone https://code.europa.eu/pvgis/pvgis
   ---> 100%
   

2. Step in the source code directory

   $ cd pvgis
   

3. Install in editable mode

   $ pip install -e ."[all]"
   ---> 100%
   

pip install .[dev]`.

uv & direnv¶

For active development with automatic environment management, a nice way is to combine the use of direnv and uv

Prerequisites¶

1. Install uv

2. Install direnv

3. Hook direnv to your shell

4. Consult Restoring the PS1, alternatively Override $PS1

5. Use uv as an environment builder

Setup the project¶

1. Clone the source code¶

See above

2. Let direnv manage the virtual environment¶

You may use the following configuration for direnv : copy it in a file named .envrc, inside the root directory of PVGIS' source code.

export VIRTUAL_ENV=.pvgis-prototype_virtual_environment
export UV_PROJECT_ENVIRONMENT=.pvgis-prototype_virtual_environment
layout uv
export CUSTOM_PS1=mycustomPS1

and run

direnv allow

After this, the virtual environment activates automatically whenever we cd into the project directory ! Plus, it deactivates once we cd out of the project directory !

3. Install PVGIS in editable mode¶

We can install PVGIS in editable mode -- every modification to the source code is directly reflected at runtime.

uv pip install -e .

Want to install all of PVGIS ?

uv pip install -e .[all]

This includes the core API, the CLI, the Web API and MkDocs to build the documentation.

PDM¶

Using PDM, you can seamlessly establish a virtual environment and install PVGIS in an editable mode.

The inclusion of a pdm.lock file in the source code repository, ensures the installation of the exact dependencies needed to setup a development environment.

1. Clone the latest version from the source repository :

   $ git clone https://code.europa.eu/pvgis/pvgis
   ---> 100%
   $ cd pvgis
   

2. Install PVGIS using PDM

   $ pdm install
   ---> 100%
   

   This will create a virtual environment and install PVGIS along with its dependencies.

3. Activate the virtual environment

   $ eval $(pdm venv activate in-project)
   

4. Alternatively, PDM can run a command in a virtual environment without activating it

Conda¶

In order to install the software using conda (instructions for installing conda can be found here):

1. First clone the software to get the latest changes:

   $ git clone https://code.europa.eu/pvgis/pvgis
   ---> 100%
   

2. Then, navigate into the source code directory:

   $ cd pvgis
   

3. Create the conda environment by running the following command. This will create an new conda environment named pvgis and install the PVGIS software along with its dependencies using the environment.yml file that is distributed with the software:

   $ conda env create
   ---> 100%
   

4. Finally, activate the conda environment:

   $ conda activate pvgis
   

Verify¶

We can verify the installation was successful by running any command (i.e. pvgis-prototype) or asking for the version of the installed package :

pvgis-prototype --version

PVGIS prototype version: 0.1.dev93+g63d51f564.d20251201

That was it! Happy coding!

After the installation ..¶

• Interact with PVIS through the command line interface (CLI)
• Run the Web API server
• Use the API in your scripts

Uninstall¶

Uninstalling everything is as easy as removing the dedicated environment. However, instead of using the rm -rf command which might be risky if accidentally executed for a different directory than the intended one, a safer way is to move unwanted data in the tmp directory.

mv .pvgis_virtual_environment/ /tmp/