---
title: "Connect with pyTigerGraph"
component: "savanna"
version: "main"
module: "get-started"
html_url: "/savanna/main/get-started/connect-pytigergraph.html"
---

[View as HTML](/savanna/main/get-started/connect-pytigergraph.html)

# Connect with pyTigerGraph

[pyTigerGraph](https://www.tigergraph.com/docs/pytigergraph/current/intro/) is TigerGraph's Python client. Use it to call a Savanna workspace from a script or application: run installed queries, read and write vertices and edges, and work with the same graph you built in the console.

This page gets you from install to a successful call against your workspace.

## Before you start

* A running Savanna [workspace](../workgroup-workspace/workspaces/workspace.md) with a graph on it. If you do not have one yet, [build a graph in the console](first-graph-ui.md) first.
* A database secret for that workspace. See [Create a database secret](../administration/settings/how2-create-database-secret.md).
* Python with `pip` on the machine that will run your script.

pyTigerGraph talks to the **workspace host**, the database behind that workspace. Authenticate with a database secret. Control-plane calls, such as creating workspaces, use `api.tgcloud.io` and an API key instead. See [Savanna REST API](../rest-api/index.md). If the workgroup uses an IP allowlist, include the machine that runs the script. See [Configure network access](../workgroup-workspace/workgroups/how2-config-network-access.md).

## Install

```bash
pip install pyTigerGraph
```

## Connect

A Savanna connection needs the workspace URL, the graph name, and a database secret.

| Argument | Required | What to use |
| --- | --- | --- |
| `host` | Yes | Your workspace URL, including `https://`. Open **Workspaces**, select the workspace, and copy its URL. A Savanna host looks like `<https://<workspace-id>.i.tgcloud.io>`. |
| `graphname` | Yes | The graph this connection uses. Create the graph in [Design Schema](../graph-development/design-schema/index.md) if you do not have one yet. |
| `gsqlSecret` | Yes | A database secret for that workspace. See [Create a database secret](../administration/settings/how2-create-database-secret.md). |

When the host contains `tgcloud`, pyTigerGraph treats the instance as TigerGraph Cloud and sends REST++ and GSQL traffic to port `443`, which is how Savanna publishes the workspace. Leave `restppPort` and `gsPort` at their defaults.

```python
from pyTigerGraph import TigerGraphConnection

conn = TigerGraphConnection(
    host="https://<workspace-id>.i.tgcloud.io",
    graphname="MyGraph",
    gsqlSecret="<database-secret>",
)

print(conn.echo())
print(conn.getVertexTypes())
```

`echo()` returns a response when the workspace host answers.`getVertexTypes()` returns the vertex type names on the graph when the secret can read it.

Read the secret from the environment so it stays out of source control:

```python
import os
from pyTigerGraph import TigerGraphConnection

conn = TigerGraphConnection(
    host=os.environ["TG_HOST"],
    graphname=os.environ["TG_GRAPHNAME"],
    gsqlSecret=os.environ["TG_SECRET"],
)
```

## Run a query

`runInstalledQuery` calls a query that is already installed on the graph. Install the query in the [GSQL Editor](../graph-development/gsql-editor/index.md) first, or from pyTigerGraph with the client's query methods.

```python
result = conn.runInstalledQuery("my_query", params={"param": "value"})
print(result)
```

Vertices, edges, schema changes, and loading jobs are covered in the [pyTigerGraph documentation](https://www.tigergraph.com/docs/pytigergraph/current/intro/). The HTTP calls underneath are the workspace [data-plane APIs](../rest-api/data-plane-apis.md).

> [!NOTE]
> Treat database secrets like passwords. Store them securely and do not commit them to source control. A database secret does not expire and remains valid until you delete or revoke it. Calls through pyTigerGraph run against the connected database and can modify or delete data.

## Troubleshooting

### Invalid URL scheme

`host` needs a scheme. Use `<https://<workspace-id>.i.tgcloud.io>`. A hostname alone raises `Invalid URL scheme`.

### Authentication failed

Create the secret in Savanna for the same workspace, and paste the full value into `gsqlSecret`. A control-plane API key is a different credential and will not authenticate this connection. See [Create a database secret](../administration/settings/how2-create-database-secret.md).

### Connection error

Confirm the workspace status is active, the host is the workspace URL, and your IP is on the workgroup allowlist when one is enabled. See [About workspaces](../workgroup-workspace/workspaces/workspace.md) and [Configure network access](../workgroup-workspace/workgroups/how2-config-network-access.md).

## Where to go next

* [Connect AI tools with MCP](connect-agent-mcp.md) when you want an agent to use the same database. TigerGraph MCP calls the database through pyTigerGraph.
* [Connect via APIs](../workgroup-workspace/workspaces/connect-via-api.md) for curl, Python, and JavaScript generated in the console.
* [Data-plane APIs](../rest-api/data-plane-apis.md) for the REST++ and GSQL endpoints the client calls.
* [Connecting to TigerGraph](https://www.tigergraph.com/docs/pytigergraph/current/getting-started/connection) in the pyTigerGraph reference.