---
last_review: "2026-05-07"
last_reviewer: "s.kaviani"
documented_code: [ ]
---

```{tags} advanced-user, how-to
```

% Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/work_items/103

# How to Configure PyLinkAhead

This guide explains how to configure the connection settings for PyLinkAhead, including
authentication and SSL certificates.

## Prerequisites

PyLinkAhead must be installed. See [Setting Up PyLinkAhead](/how_to/dev_guides/pylib/README_SETUP_pylib.md).

## Basic Setup

Create a file at `~/.pylinkahead.ini` with at least the server URL and your username:

```ini
[Connection]
url=https://your-linkahead-instance.example.com
username=YOUR_USERNAME
```

PyLinkAhead reads this file automatically on import. Once this file is in place, you can use the
client without calling `configure_connection()` in your scripts (an alternative way to pass
connection settings programmatically rather than through the `.ini` file).

By default, the client will prompt you for your password on first connection. See
the [Authentication](#authentication) section below to change this behavior.

## Authentication

The default behavior asks for your password whenever a new connection is created. You can change
this by setting `password_method` in your configuration file:

- `password_method=input`: password is queried on demand (**default**)
- `password_method=pass`: use the password manager [pass](https://www.passwordstore.org). Also
  requires `password_identifier` for the identifier within pass.
- `password_method=keyring`: use the system keyring/wallet (macOS, GNOME, KDE, Windows). Install
  the [keyring](https://pypi.org/project/keyring) package first with `pip install keyring`.
- `password_method=plain`: store password in plain text (**strongly discouraged**)

The following illustrates the recommended options:

```ini
[Connection]
username=YOUR_USERNAME

# password using "pass" password manager
#password_method=pass
#password_identifier=...

# using the system keyring/wallet (macOS, GNOME, KDE, Windows)
#password_method=keyring

#discouraged: password in plain text
#password_method=plain
#password=YOUR_PASSWORD
```

## SSL Certificate

In some cases (especially if you are testing LinkAhead) you might need to supply an SSL certificate
to allow SSL encryption.

Set the `cacert` option to the path of your SSL certificate:

```ini
[Connection]
cacert=/path/to/linkahead.ca.pem
```

## Next Steps

For a complete list of all configuration options, see the [PyLinkAhead Configuration Reference](/reference/pylib/configuration.md).

Once configured, continue with the [Python client tutorials](/tutorial/scripting/pylib/index.md).