class ansys.pyensight.core.Session(host: str = '', install_path: str | None = None, secret_key: str = '', grpc_port: int = 12345, html_hostname: str | None = None, html_port: int | None = None, ws_port: int | None = None, session_directory: str | None = None, timeout: float = 120.0, rest_api: bool = False, sos: bool = False)#

Provides for accessing an EnSight Session instance.

The Session object wraps the various connections to an EnSight instance. It includes the location of the installation and the gRPC, HTML and WS ports used to talk to the EnSight session. In most cases, a Session instance is created using Launcher class methods, but if the EnSight session is already running, an instance can be created directly to wrap this running EnSight session.

If the Session object is created via a Launcher start() method call, when the session object is garbage collected, the EnSight instance is automatically stopped. To prevent this behavior (and leave the EnSight instance running), set the halt_ensight_on_close property to False.

A gRPC connection is required to interact with an EnSight session. The host, gRPC port number, and secret key must be specified. The HTML and WS ports, which are used to enable the show) method, also require that an instance of the websocket server is running.

hoststr, optional

Name of the host that the EnSight gRPC service is running on. The default is "", which is the localhost.

install_pathstr, optional

Path to the CEI directory to launch EnSight from. The default is None.

secret_keystr, optional

Shared session secret key for validating the gRPC communication. The default is "".

grpc_portint, optional

Port number of the EnSight gRPC service. The default is 12345.

html_hoststr, optional

Optional hostname for html connections if different than host Used by Ansys Lab and reverse proxy servers

html_portint, optional

Port number of the websocket server’s HTTP server. The default is None.

ws_portint, optional

Port number of the websocket server’s WS server. The default is None.

session_directorystr, optional

Directory on the server for local data storage. The default is None.

timeoutfloat, optional

Number of seconds to try a gRPC connection before giving up. The default is 120.

rest_apibool, optional

Whether to enable the EnSight REST API for the remote EnSight instance. The default is False.

sosbool, optional

Whether the remote EnSight instance is to use the SOS (Server of Servers) feature. The default is False.


>>> from ansys.pyensight.core import Session
>>> session = Session(host="", grpc_port=12345, http_port=8000, ws_port=8100)
>>> from ansys.pyensight.core import LocalLauncher
>>> session = LocalLauncher().start()
>>> # Launch an instance of EnSight, then create a second connection to the instance
>>> from ansys.pyensight.core import LocalLauncher, Session
>>> launched_session = LocalLauncher().start()
>>> # Get a string that can be used to create a second connection
>>> session_string = str(launched_session)
>>> # Create a second connection to the same EnSight instance
>>> connected_session = eval(session_string)


Session.add_callback(target, tag, attr_list, ...)

Register a callback with an event tuple.


Add a new ENSOBJ object instance to the hash table.


Capture the current EnSight instance state.


Close the session.

Session.cmd(value[, do_eval])

Run a command in EnSight and return the results.

Session.copy_from_session(local_prefix, filelist)

Copy a collection of files out of the EnSight session.

Session.copy_to_session(local_prefix, filelist)

Copy a collection of files into the EnSight session.

Session.download_pyansys_example(filename[, ...])

Download an example dataset from the ansys/example-data repository.

Session.ensight_version_check(version[, ...])

Check if the session is a specific version.

Session.exec(function, *args[, remote])

Run a function containing EnSight API calls locally or in the EnSight interpreter.


Return the current EnSight scene as a geometry file.

Open the documentation for PyEnSight in a web browser.

Session.load_data(data_file[, result_file, ...])

Load a dataset into the EnSight instance.

Session.load_example(example_name[, ...])

Load an example dataset.


Get any existing proxy object associated with an ID.


Generate a string that, for a given ENSOBJ object ID, returns a proxy object instance.


Remove a callback that the :func`add_callback<ansys.pyensight.core.Session.add_callback>` method started.

Session.render(width, height[, aa])

Render the current EnSight scene and return a PNG image.


Restore the current EnSight instance state.


Run an EnSight Python script file.[what, width, height, ...])

Capture the current EnSight scene or otherwise make it available for display in a web browser.






Value of CEI_HOME for the connected EnSight session.


Suffix string of the connected EnSight session.


Core EnSight API wrapper.


The gRPC wrapper instance used by this session to access EnSight.


Flag for indicating whether to halt EnSight on close.


Hostname of the system hosting the EnSight instance.


Hostname of the system hosting the EnSight web server instance.


Port supporting HTML interaction with EnSight.


Flag indicating if the session is running in a Jupyter notebook and should use the display features of that interface.


Current language specification for the EnSight session.


Reference to the launcher instance if a launcher was used to instantiate the session.

The session name is a unique identifier for this Session instance.


Flag indicating if the remote EnSight session supports the REST API.


Secret key used for communication validation in the gRPC instance.


Flag indicating if the remote EnSight session is running in SOS (Server of Server) mode.


Amount of time in seconds to try a gRPC connection before giving up.


Port supporting WS interaction with EnSight.