StartExternalSession starts an external process that can be used to implement an external evaluator session in which there are multiple evaluations requested by ExternalEvaluate.
In StartExternalSession[assoc], elements of the association can include:

	"System"	the external system or language to start
	"Evaluator"	the specific evaluator to execute code
	"Name"	the registered name of an evaluator
	"ID"	a unique identifier
	"ReturnType"	type of object to return ("String", "Expression", ...)
	"Prolog"	code to run before the command
	"Epilog"	code to run after the command
	"SessionProlog"	code to run before the session
	"SessionEpilog"	code to run after the session

"System" is the only required key; all others are optional.
In StartExternalSession[sys], possible choices of sys include:

	"Python"	Python
	"NodeJS"	JavaScript running through Node.js
	"Julia"	Julia
	"Ruby"	Ruby
	"R"	R
	"Shell"	Bash, Sh, Zsh, ...
	"Jupyter"	Jupyter kernel
	"SQL"	SQL database
	"SQL-JDBC"	SQL database using JDBC

Possible settings for "type" in StartExternalSession[sys"type",…], or for "ReturnType", are dependent on the evaluation system, and typically include:
"Expression" attempt to convert to a Wolfram Language expression

"String" give the raw string output by the external evaluator
The possible settings for evaluator in StartExternalSession[{sys,"Evaluator"evaluator},…] depend on sys, and include:
"path" path to a language executable

DatabaseReference[…] an SQL database connection

SQLConnection[…] an SQL-JDBC database connection
Typically, StartExternalSession uses the setting "ReturnType""Expression".
StartExternalSession[{"sys",opts}] is equivalent to StartExternalSession[<|"System""sys",opts|>].
StartExternalSession[{sys,"ID""id",…}] either returns an already running session with the given "id" or starts a new session with the unique "id".
ExternalEvaluators gives a list of evaluator systems that can be used.
ExternalSessions gives a list of active external sessions.
DeleteObject[ExternalSessionObject[…]] kills and removes an external session started by StartExternalSession.

Examples

open all close all

Basic Examples (2)

Start an external Python session, automatically discovering any usable installations:

Wolfram Language code: session = StartExternalSession["Python"]

Evaluate code in the session:

Wolfram Language code: ExternalEvaluate[session, "1+1"]

Stop the session with DeleteObject:

Wolfram Language code: DeleteObject[session]

Start a new Python session in a provisioned environment:

Wolfram Language code:

session = StartExternalSession[
	{
	"Python", 
	"Evaluator" -> <|
	"Dependencies" -> {"emoji"}, 
	"EnvironmentName" -> "myenv", 
	"PythonRuntime" -> "3.11"
	|>
	}
	]

Wolfram Language code:

ExternalEvaluate[
	session, 
	"import emoji; emoji.emojize('Emojis are :thumbs_up:')"
	]

Scope (16)

Basic Uses (2)

Multiple external sessions can be run simultaneously:

Wolfram Language code: {StartExternalSession["Python"], StartExternalSession["NodeJS"], StartExternalSession["Julia"]}

Delete the session objects:

Wolfram Language code: DeleteObject[%]

Start an external Python session using the executable in /usr/bin/python3:

Wolfram Language code: session = StartExternalSession[<|"System" -> "Python", "Evaluator" -> "/usr/bin/python3"|>]

Use the session for multiple calls to ExternalEvaluate:

Wolfram Language code: ExternalEvaluate[session, "x='hello world'"]

Wolfram Language code: ExternalEvaluate[session, "x"]

Stop the session with DeleteObject:

Wolfram Language code: DeleteObject[session]

Session Options (14)

"ReturnType" (4)

For most systems, the default return type is "Expression":

Wolfram Language code: session = StartExternalSession["Python"]

Wolfram Language code: value = ExternalEvaluate[session, "2+2"]

Wolfram Language code: IntegerQ[value]

Delete the session objects:

Wolfram Language code: DeleteObject[session]

Numbers, strings, lists and associations are automatically imported for the "Expression" return type:

Wolfram Language code: session = StartExternalSession["Python"]

Wolfram Language code: result = ExternalEvaluate[session, "[2, 3, 'foobar', (1, 1)]"]

Wolfram Language code: Map[Head, result]

Delete the session objects:

Wolfram Language code: DeleteObject[session]

The return type of "String" returns a string of the result in the external language:

Wolfram Language code: session = StartExternalSession["Python" -> "String"]

Wolfram Language code: result = ExternalEvaluate[session, "[1, 2, u'א']"]

Wolfram Language code: StringQ[result]

Delete the session objects:

Wolfram Language code: DeleteObject[session]

When using a database, the default return type is "Dataset":

Wolfram Language code: db = DatabaseReference[FindFile["ExampleData/ecommerce-database.sqlite"]];

Wolfram Language code: session = StartExternalSession[db]

Wolfram Language code: ExternalEvaluate[session, "select officeCode as pk, phone from offices"]

"ReturnType" can be used to return data in a different form:

Wolfram Language code: sessionRows = StartExternalSession[{db, "ReturnType" -> "Rows"}];

Wolfram Language code: ExternalEvaluate[sessionRows, "select officeCode as pk, phone from offices"]

Wolfram Language code: sessionNamedRows = StartExternalSession[{db, "ReturnType" -> "NamedRows"}];

Wolfram Language code: ExternalEvaluate[sessionNamedRows, "select officeCode as pk, phone from offices"]

Wolfram Language code: sessionColumns = StartExternalSession[{db, "ReturnType" -> "Columns"}];

Wolfram Language code: ExternalEvaluate[sessionColumns, "select officeCode as pk, phone from offices"]

Wolfram Language code: sessionNamedColumns = StartExternalSession[{db, "ReturnType" -> "NamedColumns"}];

Wolfram Language code: ExternalEvaluate[sessionNamedColumns, "select officeCode as pk, phone from offices"]

Delete the session objects:

Wolfram Language code: DeleteObject /@ {session, sessionRows, sessionNamedRows, sessionColumns, sessionNamedColumns};

"Evaluator" (3)

Evaluate code using a specified "Evaluator":

Wolfram Language code:

session = StartExternalSession[
	{"Python", "Evaluator" -> "/opt/homebrew/bin/python3"}]

Wolfram Language code: ExternalEvaluate[session, "import sys; sys.executable"]

Delete the session objects:

Wolfram Language code: DeleteObject[session]

An Association can be used to start a Python provisioned environment:

Wolfram Language code:

session = StartExternalSession[
	{
	"Python", 
	"Evaluator" -> <|
	"Dependencies" -> {"emoji"}, 
	"PythonRuntime" -> "3.11", 
	"EnvironmentName" -> "my-emoji-env"
	|>
	}
	]

Use the session to evaluate the code:

Wolfram Language code:

ExternalEvaluate[session, 
	"import emoji; import sys; [emoji.emojize('Emojis are :thumbs_up:'), sys.version, sys.executable]"]

Wolfram Language code:

{"Emojis are 👍", "3.11.4 (main, Jul  5 2023, 08:41:25) [Clang 14.0.6 ]", "/Users/WolframUser/Library/Mathematica/ApplicationData/ExternalEvaluate/Python/Venv/my-emoji-env/bin/python"}

Delete the session objects:

Wolfram Language code: DeleteObject[session]

When using a File with the "SQL" evaluator, the target can be a path to an SQLite file or a DatabaseReference specification:

Wolfram Language code: s1 = StartExternalSession[{"SQL", "Evaluator" -> FindFile["ExampleData/ecommerce-database.sqlite"]}];

Wolfram Language code: ExternalEvaluate[s1, "select officeCode, city from offices"]

Wolfram Language code:

s2 = StartExternalSession[{"SQL", "Evaluator" -> 
DatabaseReference[URL["postgres://localhost/template1"]]}];

Wolfram Language code:

ExternalEvaluate[{"SQL", "Evaluator"  -> s2 }, "SELECT NOW() as now, NOW()::date as date, interval '1 day' as interval, '1.23'::decimal as decimal"]

Delete the session objects:

Wolfram Language code: DeleteObject /@ {s1, s2}

"Name" (1)

Wolfram Language code:

RegisterExternalEvaluator[
	"Python", 
	<|"Dependencies" -> {"numpy"}, "EnvironmentName" -> "my-numpy-env"|>, 
	"numpy-env"
	]

Start a session using the registered evaluator by referring to it by name:

Wolfram Language code: session = StartExternalSession[{"Python", "Name" -> "numpy-env"}]

Use the session:

Wolfram Language code: ExternalEvaluate[session, "import numpy; numpy.arange(12)"]

Close the session:

Wolfram Language code: DeleteObject[session]

"ID" (1)

Start an evaluator with a given "ID":

Wolfram Language code: session = StartExternalSession[{"Python", "ID" -> "my-unique-id"}]

The operation is idempotent; starting a session with the same "ID" will return the same running session:

Wolfram Language code: StartExternalSession[{"Python", "ID" -> "my-unique-id"}]

You can check that there is only one running session, even if you run StartExternalSession two times:

Wolfram Language code: ExternalSessions[]

Close the session:

Wolfram Language code: DeleteObject[session]

"SessionProlog" (2)

Use "SessionProlog" to perform a side effect at the start of a session:

Wolfram Language code: session = StartExternalSession[{"Python", "SessionProlog" -> "print('session started')"}];

Wolfram Language code: ExternalEvaluate[session, "print('evaluating code'); 2+2"]

Delete the session objects:

Wolfram Language code: DeleteObject[session]

Start an external session and import a library at the beginning of the session:

Wolfram Language code: session = StartExternalSession[<|"System" -> "Python", "SessionProlog" -> "import math"|>]

Evaluate a function from the imported library:

Wolfram Language code: ExternalEvaluate[session, "math.factorial(4)"]

Delete the session object:

Wolfram Language code: DeleteObject[session]

"SessionEpilog" (1)

Use "SessionEpilog" to perform a side effect at the end of a session:

Wolfram Language code: session = StartExternalSession[{"Shell", "SessionEpilog" -> "echo closing session"}];

Wolfram Language code: ExternalEvaluate[session, "date"]

Delete the session object:

Wolfram Language code: DeleteObject[session]

"Prolog" (1)

Use "Prolog" to perform a side effect before every evaluation:

Wolfram Language code: session = StartExternalSession[{"Python", "SessionProlog" -> "n=0", "Prolog" -> "print('n was', n)"}];

Wolfram Language code: ExternalEvaluate[session, {"n += 3", "n += 3"}]

Delete the session object:

Wolfram Language code: DeleteObject[session]

"Epilog" (1)

Use "Epilog" to perform a side effect after every evaluation:

Wolfram Language code:

session = StartExternalSession[{"Python", "SessionProlog" -> "n=0", "Prolog" -> "print('n was', n)", "Epilog" -> "print('n is', n)"}];

Wolfram Language code: ExternalEvaluate[session, {"n += 3", "n += 3"}]

Delete the session object:

Wolfram Language code: DeleteObject[session]

Properties & Relations (5)

Each session runs in its own process:

Wolfram Language code: sessions = Table[StartExternalSession["Python"], 2]

The process IDs for each session are different:

Wolfram Language code: ExternalEvaluate[#, "import os; os.getpid()"]& /@ sessions

Delete the session objects:

Wolfram Language code: DeleteObject[sessions]

If only the language is specified, when possible, an evaluator is automatically provisioned:

Wolfram Language code: session = StartExternalSession["Python"];

Wolfram Language code: session["Evaluator"]

The evaluator is stored under $UserBaseDirectory:

Wolfram Language code: ExternalEvaluate[session, "import sys; [sys.version, sys.executable]"]

Stop the session:

Wolfram Language code: DeleteObject[session]

Use ExternalEvaluators to find all available evaluators for a system:

Wolfram Language code: evaluators = ExternalEvaluators["Shell"]

Use StartExternalSession to start a session from it:

Wolfram Language code: session = StartExternalSession[First @ evaluators]

Wolfram Language code: ExternalEvaluate[session, "ping -c 1 wolfram.com"]

Manually close the session:

Wolfram Language code: DeleteObject[session];

Start a database session:

Wolfram Language code: db = DatabaseReference[FindFile["ExampleData/ecommerce-database.sqlite"]]

Wolfram Language code: session = StartExternalSession[db]

Run a query:

Wolfram Language code: ExternalEvaluate[session, "SELECT * from offices limit 5"]

Manually close the session:

Wolfram Language code: DeleteObject[session];

External language cells implicitly call StartExternalSession:

Wolfram Language code: ExternalSessions[]

x=2

A new session has been started:

Wolfram Language code: ExternalSessions[]

By default, all cells of a given system use that session:

x*x

End the session so that subsequent evaluations start in a new session:

Wolfram Language code: DeleteObject[Last[%%]]

Top

More Learning

Tech Support

Data Science, Finance & Business

Engineering

Science & Technology

Technology for Education

Education Initiatives

Get Started

Grow Your Skills

Work with Us

Educational Programs for Adults

Educational Programs for Youth

Read

StartExternalSession

Details

Examples

Basic Examples (2)

Scope (16)

Basic Uses (2)

Session Options (14)

"ReturnType" (4)

"Evaluator" (3)

"Name" (1)

"ID" (1)

"SessionProlog" (2)

"SessionEpilog" (1)

"Prolog" (1)

"Epilog" (1)

Properties & Relations (5)

Text

CMS

APA

BibTeX

BibLaTeX

	"path"	path to a language executable
	DatabaseReference[…]	an SQL database connection
	SQLConnection[…]	an SQL-JDBC database connection

StartExternalSession

Details

Examples

Basic Examples (2)

Scope (16)

Basic Uses (2)

Session Options (14)

"ReturnType" (4)

"Evaluator" (3)

"Name" (1)

"ID" (1)

"SessionProlog" (2)

"SessionEpilog" (1)

"Prolog" (1)

"Epilog" (1)

Properties & Relations (5)

See Also

Related Guides

Related Workflows

History

Text

CMS

APA

BibTeX

BibLaTeX

StartExternalSession   