Installing Arches


Once you have all the dependencies taken care of (and Elasticsearch is running) you are ready to install Arches.


If you are a developer hoping to contribute to the Arches project, please check out Creating a Development Environment.

1. Create and enter a new directory called Projects

mkdir Projects && cd Projects

2. Create a virtual environment called ENV

On some linux distributions, if the python version is less than 3.7, entering the following command may yield an error but it should alert you to any depdencies you may need to install, after which you’ll be able to run this command.

python -m venv /path/to/new/ENV

3. Activate the virtual environment

Note that when calling source to activate your ENV, you’ll likely need to type the relative path to it.

Linux and macOS:

source ENV/bin/activate



When you activate your virtual environment, your command prompt will be prefixed with (ENV). If you need to deactivate it for any reason, run deactivate.

4. Install Arches into your virtual environment

Use the following to get the latest stable release of Arches:

pip install arches

5. Create a new Arches Project

Now that Arches is installed, you can make a Project. This is where you will make all of the customizations and branding that will make one installation of Arches different from the next. The name of your project should only be lowercase, and should use underscores instead of spaces or hyphens. The example below uses my_project. You can add --directory path/to/dir to change the directory your new project will be created in.

Linux and macOS:

arches-project create my_project


python ENV\Scripts\arches-project create my_project


At this level, “projects” are completely different from the mobile data collection “projects” that are mentioned elsewhere in this documentation.

6. Update

Before you continue, you may need to open my_project\my_project\ and change some environment-specific settings.

  • Depending on your Postgres/PostGIS installation, you may need to uncomment the DATABASES section and change the username and password, as well as the name of your PostGIS template database. If you will have multiple Arches projects using the same Postgres server, make sure to change the database name here as well.

  • On Windows, you must specify the path to your GDAL library. Add the following line. Be sure to adjust the path as necessary for your GDAL installation, and note the forward slashes:

    GDAL_LIBRARY_PATH = "C:/OSGeo4W64/bin/gdal201.dll"
  • See Arches System Settings for a full rundown of how settings are handled in Arches.

7. Setup the database

To begin working with your Project, first enter it:

cd my_project

and then (with ElasticSearch running) run:

python setup_db


You may be prompted to enter a password for the postgres user, depending on your OS and how you installed Postgres/Postgis. Generally, our installation scripts set this password to postgis.

8. Run the development server

To confirm things are working, run:

python runserver

and navigate to localhost:8000 in a browser.

The default login credentials are ‘admin’ for both username and password. To change this password and create new users, navigate to localhost:8000/admin.

Next steps…

Now that you have Arches installed and a Project created, you are ready to begin.

  • Modify some Initial Configuration settings

  • In order to allow API access to your instance, to support the use of the Arches Collector mobile app, you must register an Arches application.

  • Read more about Projects and Packages

  • For a quick start that will create an example database schema in your new Arches project (and allow you to begin recording data right away), you can load a sample package with the following command

    python packages -o load_package -s -db true

    This example package has a full set of Resource Models, Branches, and Concepts that are generally based on the original Arches HIP Contents.


    If you get an “invalid package source” error, please download the zipfile (use the url in the command) and run the same command pointing to the location of the downloaded zipfile.

General Troubleshooting

  • On macOS, If you get this error


    ValueError: –enable-zlib requested but zlib not found, aborting.

    try running xcode-select --install (reference)

  • Getting a connection error like this (in the dev server output or in the browser)


    ConnectionError: ConnectionError(<urllib3.connection.HTTPConnection object at 0x0000000005C6BC50>: Failed to establish a new connection: [Errno 10061] No connection could be made because the target machine actively refused it) caused by: NewConnectionError(<urllib3.connection.HTTPConnection object at 0x0000000005C6BC50>: Failed to establish a new connection: [Errno 10061] No connection could be made because the target machine actively refused it)

    means Arches is not able to communicate with ElasticSearch. Most likely, ElasticSearch is just not running, so just start it up and reload the page. If you can confirm that it is running, make sure Arches is pointed to to correct port.

  • Postgres password authentication error


    django.db.utils.OperationalError: FATAL: pw authentification failed for user postgres

    Most likely you have not correctly set the database credentials in your file. Many of our install scripts set the db user to postgres and password to postgis, so that’s what Arches looks for by default. However, if you have changed these values (particularly if you are on Windows and had to enter a password during the Postgres/PostGIS installation process), the new values must be reflected in in or


    On Windows, you can avoid having to repeatedly enter the password while running commands in the console by setting the PGPASSWORD environment variable: set PGPASSWORD=<your password>.