You can configure the Python client library using a YAML file, environment
variables, a YAML string, or a `dict`.

## Authentication configuration

There are multiple ways to manage the OAuth credentials needed to access the
Google Ads API. The approach you choose affects which configuration fields you use. For
more information, see the [authentication](https://developers.google.com/google-ads/api/docs/client-libs/python/authentication) guide.

## Configuration using YAML file

You can specify a YAML file to use when initializing the client that contains
the necessary information needed to make requests to the Google Ads API. This file is
accessed when a client is initialized using the `load_from_storage` method. The
easiest way to generate this file is to copy the
[`google-ads.yaml`](https://github.com/googleads/google-ads-python/blob/HEAD/google-ads.yaml) example from the GitHub repository and modify
it to include your credentials, including your refresh token, client ID, and
client secret.

If you don't provide a path, the library looks in your `$HOME` directory for the
file:

    from google.ads.googleads.client import GoogleAdsClient

    client = GoogleAdsClient.load_from_storage()

To specify a location where the `google-ads.yaml` file is located, you can pass
the path as a string to the method when calling it:

    from google.ads.googleads.client import GoogleAdsClient

    client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

You can also specify the path by defining a specific environment variable:

    import os
    from google.ads.googleads.client import GoogleAdsClient

    os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
    client = GoogleAdsClient.load_from_storage()

If both values are provided---a path is passed into the method, and the
environment variable is present---then the library prioritizes the path passed
into the method.

## Configuration using environment variables

You can store all of your client configuration as environment variables, which
are read when using the client's `load_from_env` method. Environment variables
should have the same name as those defined in the `google-ads.yaml` file, but
must be all uppercase and prefixed with the `GOOGLE_ADS_` namespace. For
example, `client_id` should be stored as `GOOGLE_ADS_CLIENT_ID`.

Environment variables are commonly defined in a bash configuration file such as
a `.bashrc` or `.bash_profile` file located in the `$HOME` directory. They can
also be defined using the command line.

> [!NOTE]
> **Note:** These instructions assume you're using `bash`. If you're using a different shell, consult documentation on how to set environment variables in your shell.

Here are some basic steps to define an environment variable using a `.bashrc`
file in a terminal:

    # Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
    # the bottom of your .bashrc file.
    echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
    # Update your bash environment to use the most recently updated
    # version of your .bashrc file.
    source ~/.bashrc

Environment variables can also be set in your terminal instance directly from
the command line:

    export GOOGLE_ADS_CLIENT_ID=1234567890
    echo $GOOGLE_ADS_CLIENT_ID

The `load_from_env` method loads configuration data from the `environ` attribute
on Python's built-in `os` module. For example:
`os.environ["GOOGLE_ADS_CLIENT_ID"]`

Here's an example of how to initialize a client instance with configuration from
environment variables:

    from google.ads.googleads.client import GoogleAdsClient

    client = GoogleAdsClient.load_from_env()

In order to configure `logging` through environment variables, the configuration
value must be a JSON object that matches the structure of the YAML keys in the
sample [`google-ads.yaml`](https://github.com/googleads/google-ads-python/blob/HEAD/google-ads.yaml) configuration file.

Here's an example of how this could be set using a `.bashrc` file:

    export GOOGLE_ADS_LOGGING='{
      "version": 1,
      "disable_existing_loggers": false,
      "formatters": {
        "default_fmt": {
          "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
          "datefmt": "%Y-%m-%d %H:%M:%S"
        }
      },
      "handlers": {
        "default_handler": {
          "class": "logging.StreamHandler",
          "formatter": "default_fmt"
        }
      },
      "loggers": {
        "": {
          "handlers": ["default_handler"],
          "level": "INFO"
        }
      }
    }'

Key point: If the environment variable `GOOGLE_ADS_CONFIGURATION_FILE_PATH` is
set when the `load_from_env` method is called, then configuration values are
retrieved from the `google-ads.yaml` file located at the specified path, not
from the environment variables described earlier.

## Configuration using a YAML string

If you have read a YAML file into memory, you can provide it directly to the
client on initialization. To do this, use the `load_from_string` method:

    from google.ads.googleads.client import GoogleAdsClient

    with open("/path/to/yaml", "r", encoding="utf-8") as handle:
        yaml_content = handle.read()

    client = GoogleAdsClient.load_from_string(yaml_content)

## Configuration using a `dict`

You can pass a `dict` directly to the `load_from_dict` method. For example:

    from google.ads.googleads.client import GoogleAdsClient

    credentials = {
        "refresh_token": "YOUR_REFRESH_TOKEN",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "use_proto_plus": True,
    }

    client = GoogleAdsClient.load_from_dict(credentials)

## Configuration fields

The client library configuration supports the following fields.

### Authentication

Only use one of these groups of fields, depending on which authentication
approach you're using:

- Single-user with application default credentials ([documentation](https://developers.google.com/google-ads/api/docs/client-libs/python/authentication#single-user-gcloud-cli))
  - `use_application_default_credentials`: Whether the library should use application default credentials (ADC) for authentication (supported in `google-ads` `v28.3.0` and later).
- Single-user with OAuth tokens ([documentation](https://developers.google.com/google-ads/api/docs/client-libs/python/authentication#single-user-tokens))
  - `client_id`: Your OAuth client ID.
  - `client_secret`: Your OAuth client secret.
  - `refresh_token`: Your OAuth refresh token.
- Service-account ([documentation](https://developers.google.com/google-ads/api/docs/client-libs/python/authentication#service-account))
  - `json_key_file_path`: A path to a local private key file. This is used for authenticating using a service account.
  - `impersonated_email`: Optional email address of the account to impersonate when using Google Workspace domain-wide delegation.

### Library behavior

These fields dictate the behavior of the library:

- `logging`: See [log configuration](https://developers.google.com/google-ads/api/docs/client-libs/python/configuration#logging-config-fields) details.
- `http_proxy`: See the [proxy documentation](https://developers.google.com/google-ads/api/docs/client-libs/python/proxy).
- `use_proto_plus`: **Required.** Whether or not to use proto-plus messages (`True` or `False`). See the [protobuf messages](https://developers.google.com/google-ads/api/docs/client-libs/python/protobuf-messages) documentation.

### Request-level configuration

- `linked_customer_id`: See the [linked-customer-id documentation](https://developers.google.com/google-ads/api/docs/concepts/call-structure#linked-customer-id).
- `login_customer_id`: See the [login-customer-id documentation](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid).
- `endpoint`: Optional alternative Google Ads API endpoint address.
- `ads_assistant`: Optional identifier for the Google Ads API Assistant header.

### Environment variables

To configure the library using environment variables, use the following:

- `GOOGLE_ADS_ADS_ASSISTANT`
- `GOOGLE_ADS_CLIENT_ID`
- `GOOGLE_ADS_CLIENT_SECRET`
- `GOOGLE_ADS_CONFIGURATION_FILE_PATH`
- `GOOGLE_ADS_ENDPOINT`
- `GOOGLE_ADS_HTTP_PROXY`
- `GOOGLE_ADS_IMPERSONATED_EMAIL`
- `GOOGLE_ADS_JSON_KEY_FILE_PATH`
- `GOOGLE_ADS_LINKED_CUSTOMER_ID`
- `GOOGLE_ADS_LOGIN_CUSTOMER_ID`
- `GOOGLE_ADS_LOGGING`
- `GOOGLE_ADS_REFRESH_TOKEN`
- `GOOGLE_ADS_USE_PROTO_PLUS`
- `GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS` (supported in `v28.3.0` and later)

### Log configuration

Log fields, which are fields underneath the `logging` configuration field, are
derived directly from the `logging.config` built-in module because the library
passes all fields under the `logging` namespace directly to the
[`logging.config.dictConfig`](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig) method. See the
[logging guide](https://developers.google.com/google-ads/api/docs/client-libs/python/logging) for complete details.

- `version`: An integer value representing a schema version.
- `disable_existing_loggers`: Whether loggers configured elsewhere in the application should be disabled.
- `formatters`: Dictionaries defining different kinds of formatters.
- `handlers`: Dictionaries defining different handlers, which control where logs are written to and which formatters should be used.
- `loggers`: Dictionaries defining different types of loggers, which include a handler and a log level.