Linux

This guide describes installation for apt-based Linux distributions like Debian and Ubuntu.

Raspberry Pi

For Raspberry Pi, we recommend the easier installation with evcc Linux Image.

Note

For other Linux distributions, see the Docker guide or Manual Installation section.

First Installation

1. Install

   Open a terminal and install the required dependencies:

   sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl

   Add the evcc APT repository:

   Release

   Current stable release

   curl -1sLf 'https://dl.evcc.io/public/evcc/stable/setup.deb.sh' | sudo -E bash

   Nightly

   Development release. Updated daily. May be unstable.

   curl -1sLf 'https://dl.evcc.io/public/evcc/unstable/setup.deb.sh' | sudo -E bash

   Update the package list and install evcc:

   sudo apt update
   sudo apt install -y evcc

   Note

   During installation, a user evcc is created, so ensure the logged-in user does not have the name evcc.

   Note

   If a serial interface is used, you may need to run sudo usermod -a -G plugdev evcc. This adds the user evcc to the plugdev group, granting access to plug-in devices (USB, serial interface, etc.) without root privileges.

2. Start

   sudo systemctl start evcc

3. Set up

   Open the evcc web interface in your browser: http://localhost:7070. Set an administrator password and configure your devices directly via the web interface.

Thanks to Cloudsmith for hosting the repository!

Configuration

evcc can be configured via the web interface or a configuration file.

Recommended

Configuration via the web interface is the easiest way to set up evcc.

Web Interface (recommended)

After first start, you can configure evcc directly in the browser at http://localhost:7070. The settings are automatically saved in the database.

Configuration File (traditional)

Alternatively, you can use an evcc.yaml configuration file. See Configuration for details on creating the configuration file.

Caution

The configuration file must be placed at /etc/evcc.yaml.

• Create the configuration file according to the guide and save it at /etc/evcc.yaml

• Restart the evcc server:

  sudo systemctl restart evcc

• Access the evcc interface at http://localhost:7070

Upgrades

To update to the latest version of evcc, follow this guide:

• Check the releases for breaking changes (BC) for your installation

• Open a terminal

• Update the package list:

  sudo apt update

• Upgrade evcc:

  sudo apt --only-upgrade install -y evcc

Note

If the unstable repository (nightly versions) has been added, updates will always install the latest available nightly version.

If this is no longer desired, the unstable repository can be removed using sudo rm /etc/apt/sources.list.d/evcc-unstable.list.

Downgrade

If you need to go backwards for any reason, you can do so with this command:

  sudo apt install evcc=x.xxx.x # Version Number

System Service

evcc runs as a background system service. Here’s some useful commands to control it:

sudo systemctl status evcc # shows status
sudo systemctl start evcc # start the service, if it isn't already running
sudo systemctl stop evcc # stops the service
sudo systemctl restart evcc # restart the service
sudo systemctl enable evcc # sets the service to run at boot
sudo systemctl disable evcc # stops the service running at boot

Testing

Check the installation

• Show the running evcc service:

  sudo systemctl status evcc

• Check the latest log entries of the evcc service:

  sudo journalctl -u evcc --since "yesterday"

• Validate the meter configuration:

  sudo evcc -l debug meter

• Validate the charger configuration:

  sudo evcc -l debug charger

• Validate the vehicle configuration:

  sudo evcc -l debug vehicle

Open a browser and enter the following URL: http://127.0.0.1:7070.

Note

Replace 127.0.0.1 with the IP address or hostname of the computer if the browser is not opened on the same computer.

Backup and Restore

Via Web Interface (recommended)

The easiest method is to backup via the web interface. See Configuration → Backup & Restore for details.

Manual Backup

To restore the “original state” after a reinstallation, it is sufficient to back up the configuration file evcc.yaml (if used) and the database file evcc.db. The storage location is specified in the log file at program start. Typically, the configuration is located under /etc/evcc.yaml and the database under /var/lib/evcc/evcc.db.

Both files can be copied using the Linux command cp.

Example (copying from the usual storage location to the home directory):

Copy yaml: sudo cp /etc/evcc.yaml /home/pi/evcc.yaml.bak

Copy db: sudo cp /var/lib/evcc/evcc.db /home/pi/evcc.db.bak

Environment Variables & CLI Options

When installed via APT, evcc runs as a systemd service. You can customize the behavior using an override file:

sudo systemctl edit evcc

Caution

Don’t edit /lib/systemd/system/evcc.service directly.

That file is overwritten by apt on every package update and your changes will be lost. Always use a systemd drop-in via systemctl edit evcc instead.

Example

/etc/systemd/system/evcc.service.d/override.conf

[Service]
Environment="EVCC_LOG=debug,tariff:trace"
Environment="EVCC_DATABASE_DSN=/usb/evcc/evcc.db"
Environment="EVCC_NETWORK_HOST=my-evcc.local"
Environment="EVCC_NETWORK_PORT=80"
ExecStart=
ExecStart=/usr/bin/evcc --custom-css /path/to/my.css

Note

The first empty ExecStart= line is important to override the default command.

Tip

All parameters from evcc.yaml can be set as environment variables: EVCC_ + parameter name in uppercase.

For a complete list of all CLI options, see the CLI documentation.

Manual Installation

In addition to the Debian/Ubuntu APT package, we also provide other binaries for Linux.

Installation

• Download the appropriate file for your system:

  • 64-bit Intel CPU: evcc_X.XX_linux_amd64.tar.gz
  • 64-bit ARM CPU: evcc_X.XX_linux_arm64.tar.gz
  • 32-bit ARM CPU (e.g. Raspberry Pi 32-bit OS): evcc_X.XX_linux_armv6.tar.gz

• Extract the downloaded file (e.g., by double-clicking).

• The extracted folder contains an evcc program.

• Open a terminal and navigate to the new folder.

• Check if evcc works with this command:

  ./evcc -v

• You should see the current version of evcc (e.g., evcc version 0.xxx.y).

Configuration

You can configure evcc via the web interface or a configuration file. See Configuration for details.

Start evcc with:

./evcc

Then open your browser at http://localhost:7070 and follow the instructions.

Upgrade/Downgrade

Follow the steps above and replace the evcc program file with the new or previous version. The configuration does not need to be redone.

Setting up the Service

For production use, you’ll want to set up evcc as a system service. This ensures evcc starts when the computer boots and automatically restarts in case of errors.

Note

This documentation assumes Linux supports systemd.

• Run the following command to create and open an editor with a new file for the service:

  sudo nano /etc/systemd/system/evcc.service

• Copy the following content into the file:

  [Unit]
  Description=evcc
  Requires=network-online.target
  After=syslog.target network.target network-online.target
  Wants=network-online.target
  StartLimitIntervalSec=10
  StartLimitBurst=10
  
  [Service]
  ExecStart=/usr/local/bin/evcc
  Restart=always
  RestartSec=5
  
  [Install]
  WantedBy=multi-user.target

  Adjust the path of the evcc file in ExecStart if the file is located in a different directory. This also assumes that the configuration file evcc.yaml can be found at /etc/evcc.yaml. If this is not the case, add the text -c /yourpath/evcc.yaml at the end of ExecStart. Replace yourpath with the appropriate directory.

• Test the service:

  sudo systemctl daemon-reload
  sudo systemctl start evcc
  sudo systemctl status evcc

  On success, the output should contain: Active: active (running).

• Configure the service to start automatically at system boot:

  sudo systemctl enable evcc.service

For more information, see the System Service section above.