Configure PyGraphistry#

PyGraphistry can be configured for tasks such as eliminating analyst boilerplate, customizing security handling, and supporting advanced server configurations.

Configuration is for two basic APIs: the upload API for how PyGraphistry sends data to a Graphistry server, and the client API for how a URL is loaded into a user’s browser.

For server configuration, see main configuration docs. For REST API settings for uploading and viewing visualizations, see main developer documentation.

The Cascade#

PyGraphistry configuration settings resolve through the following cascade, with the top items overriding the further ones:

Priority	Name	Primary Use
5	`graph.settings(url_params={...})`	Analyst or developer fine-tuning an individual visualization’s style via
4	`graphistry.register(...)`	Analyst or developer
3	Environment variables	Developer or sysadmin
2	`graphistry.config`	Sysadmin
1	Default

Graphistry’s built-in Jupyter server comes with a predefined graphistry.config.

Settings#

General#

Setting	Default	Type	Description
`api`	3	`3` (required: JWT+Arrow)	Upload format and wire protocol. API 1 and 2 have been removed.
`certificate_validation`	`True`	boolean	Unsafe: Disable to allow ignore TLS failures such as for known-faulty CAs
`client_protocol_hostname`	`None`	FQDN, including protocol, for overriding `protocol` and `hostname` for what URL is used in browsers from displaying visualizations
`hostname`	`"hub.graphistry.com"`	string	Domain (and optional path) for where to upload data and load visualizations
`protocol`	`"https"`	`"https"` or `"http"`

1.0 API (REMOVED)#

WARNING: API v1 (api=1, api=2) has been permanently removed. The server returns HTTP 410 Gone for /etl endpoints. Use api=3 with JWT authentication.

Setting	Default	Type	Description
~~`api_key`~~	`None`	string	REMOVED - Use JWT authentication instead
~~`dataset_prefix`~~	`"PyGraphistry/"`	string	REMOVED

Usage Modes#

graph.settings(url_params={…})#

Override and add query parameters to the loaded visualization iframe by adding key/value strings to url_params. This does not control the protocol, domain, nor path, so is primarily for styling and debugging purposes.

Example#

my_graph.settings(url_params={
    'play': '0', 
    'my_correlation_id': 'session-123'
}).plot()

graphistry.register()#

Note: Setup of the environment lets developers and analysts skip manually configuring register(), which may be preferrable

Global module settings can be defined via register():

register(api=3, username='...', password='...', server=None, protocol=None, api=None, certificate_validation=None, ...)

See PyGraphistry docs for individual connectors such as .bolt(...) and .tigergraph(...).

Example: Neo4j (bolt/cypher)#

import graphistry
graphistry.register(api=3, username='...', password='...', protocol='http', server='my.server.com')

g = graphistry.bolt({'server': 'bolt://...', 'auth': ('my_user', 'my_pwd')})

g.cypher("MATCH (a)-[b]->(c) RETURN a,b,c LIMIT 10").plot()
g.cypher("MATCH (a)-[b]->(c) RETURN a,b,c LIMIT 100000").plot()
...

Environment variables#

General#

Graphistry Setting	Environment Variable	Description
`api_version`	`GRAPHISTRY_API_VERSION`
`certificate_validation`	`GRAPHISTRY_CERTIFICATE_VALIDATION`
`client_protocol_hostname`	`GRAPHISTRY_CLIENT_PROTOCOL_HOSTNAME`
`hostname`	`GRAPHISTRY_HOSTNAME`
`protocol`	`GRAPHISTRY_PROTOCOL`
	`PYGRAPHISTRY_CONFIG`	Absolute path of `graphistry.config`

1.0 API (REMOVED)#

WARNING: These environment variables are no longer functional. Use JWT authentication.

Graphistry Setting	Environment Variable	Description
~~`api_key`~~	~~`GRAPHISTRY_API_KEY`~~	REMOVED
~~`dataset_prefix`~~	~~`GRAPHISTRY_DATASET_PREFIX`~~	REMOVED

There are multiple common ways to set environment variables:

OS user login, e.g., .bashrc file
In an invocation script, MY_FLD=MY_VAL python myscript.py
The environment: section of Graphistry’s ~/docker-compose.yml for notebook or the ~/.env file. WARNING: Editing .env is preferred over editing .yml in order to simplify upgrading
In Python via os.environ['MY_FLD'] = 'MY_VAL'

graphistry.config#

Specify a json file using key/values from the Settings table.

PyGraphistry automatically checks for graphistry.config as follows:

config_paths = [
    os.path.join('/etc/graphistry', '.pygraphistry'),
    os.path.join(os.path.expanduser('~'), '.pygraphistry'),
    os.environ.get('PYGRAPHISTRY_CONFIG', '')
]

Graphistry Enterprise: Install packages into built-in Jupyter notebook#

If you are using Graphistry’s built-in Jupyter server, it autoconfigures PYGRAPHISTRY_CONFIG, graphistry.config, and PYTHONPATH.

The PYTHONPATH is automatically set to correspond to your host’s data/py_envs/* folders, so custom package installs will persist across container restarts and rebuilds.

Install new packages#

You can likely just pip install you_package and will work

Safety tip: Use pip install --no-deps your_package . This avoids risks of breaking existing GPU packages with unintended dependency upgrades.

You typically need to restart your Jupyter notebook’s Python kernel after installing new packages.

List custom package installs#

Check on your host environment, ls ./data/py_envs/*

You may also be able to check via your Jupyter notebook environment. See env to find where the custom packages are mounted, and check that folder.

Uninstall packages#

Perform the usual pip uninstall your_package command.

If there are lingering file issues, check your data/py_envs folder for any unintended files and folders.

You may need to restart your Jupyter notebook’s Python kernel after uninstalling packages to have the intended effect.

Bundled installs#

Graphistry Enterprise servers come with dependencies built-in, so you can skip this section

For custom environments, you may want to add some that PyGraphistry prebundles. Run pip install graphistry[bundle_name], with the following bundle names as common ones:

None: (pip install graphistry) - no extras
umap_learn: For CPU UMAP support
ai: For AI/ML support, including 1GB+ PyTorch install
RAPIDS.AI: You can also get far by installing the RAPIDS.ai ecosystem, especially cudf, cuml, and cugraph
For more options, see the setup.py file in the PyGraphistry Github repository

Examples#

Speed up some uploads#

import graphistry
graphistry.register(api=3, username='..', password='...')

Preset a 1.0 API key for all system users (REMOVED)#

WARNING: API v1 keys are no longer supported. Use JWT authentication with api=3.

For Jupyter notebooks, the built-in Graphistry notebook server auto-configures JWT authentication. For custom environments, use graphistry.register(api=3, username='...', password='...').

Different URLs for internal upload vs external viewing#

In scenarios like Graphistry running on a notebook server, you may prefer to send uploads to a local host (http://localhost, http://nginx, …), and tell browser client viewers to use a separate, public host and subpath (http://graphistry.site.ngo/graphistry):

import os
import graphistry

### Internal URL: PyGraphistry app -> Graphistry Server
GRAPHISTRY_HOSTNAME_PROTOCOL='https'
os.environ['GRAPHISTRY_HOSTNAME'] = "localhost"

### External URL: Webpage iframe URL -> Graphistry Server
os.environ['GRAPHISTRY_CLIENT_PROTOCOL_HOSTNAME'] = "https://graph.site.ngo/graphistry"

graphistry.register(
    api=3,
    protocol=GRAPHISTRY_HOSTNAME_PROTOCOL,
    server='localhost',
    username='MY_USERNAME',
    password='MY_PASSWORD'
)

Configure PyGraphistry

Contents

Configure PyGraphistry#

The Cascade#

Settings#

General#

~~1.0 API~~ (REMOVED)#

Usage Modes#

graph.settings(url_params={…})#

Example#

graphistry.register()#

Example: Neo4j (bolt/cypher)#

Environment variables#

General#

~~1.0 API~~ (REMOVED)#

graphistry.config#

Graphistry Enterprise: Install packages into built-in Jupyter notebook#

Install new packages#

List custom package installs#

Uninstall packages#

Bundled installs#

Examples#

Speed up some uploads#

~~Preset a 1.0 API key for all system users~~ (REMOVED)#

Different URLs for internal upload vs external viewing#

1.0 API (REMOVED)#

1.0 API (REMOVED)#

Preset a 1.0 API key for all system users (REMOVED)#