Configuring Arca

There are multiple ways to configure Arca and its backends. (The used options are described bellow.)

  1. You can initialize the class and backends directly and set it’s options via constructor arguments.
from arca import Arca, VenvBackend

arca = Arca(

This option is the most direct but it has one caveat - options set by this method cannot be overridden by the following methods.

2. You can pass a dict with settings. The keys have to be uppercase and prefixed with ARCA_. Keys for backends can be set in two ways. The first is generic ARCA_BACKEND_<key>, the second has a bigger priority ARCA_<backend_name>_BACKEND_<key>. For example the same setting as above would be written as:

arca = Arca(settings={
  "ARCA_BASE_DIR": ".custom_arca_dir",
  "ARCA_BACKEND": "arca.VenvBackend",
  "ARCA_BACKEND_CWD": "",  # this one is ignored since it has lower priority

3. You can configure Arca with environ variables, with keys being the same as in the second method. Environ variables override settings from the second method.

You can combine these methods as long as you remember that options explicitly specified in constructors cannot be overridden by the settings and environ methods.

Basic options

This section only describes basic settings, visit the cookbook for more.

Arca class

base_dir (ARCA_BASE_DIR)

Arca needs to clone repositories and for certain backends also store some other files. This options determines where the files should be stored. The default is .arca. If the folder doesn’t exist it’s created.

backend (ARCA_BACKEND)

This options tells how the tasks should be launched. This setting can be provided as a string, a class or a instance. The default is arca.CurrentEnvironmentBackend, the Current Environment Backend.


This section describes settings that are common for all the backends.


Tells backends where to look for a requirements file in the repositories, so it must be a relative path. You can set it to None to indicate that requirement file should be ignored. The default is requirements.txt. If the path file doesn’t exist in the repository than no requirements are installed.


Tells backends how long the installing of requirements can take, in seconds. The default is 120 seconds. If the limit is exceeded BuildTimeoutError is raised.


Tells backends where to look for Pipfile and Pipfile.lock files, for Pipenv. It must be a relative path to a directory. You can set it to None to indicate that Pipenv files should be ignored. The default is an empty string, the root of the repository. If there are Pipenv files in the repository alongside a requirement file than Pipenv takes precedence.

Both Pipfile and Pipfile.lock must be present in the repository for Pipenv to be used. If only one of them is present then an exception is raised. The --deploy flag is used, meaning that the Pipfile.lock must be up to date with Pipfile.


Tells Arca in what working directory the tasks should be launched, so again a relative path. The default is the root of the repository.