WOLFRAM

Wolfram Language & System Documentation Center
Wolfram Language Home Page »

StartExternalSession   
✖
StartExternalSession

Listing of External Evaluators »
Unsupported in Public CloudUpdated in 14.1[Experimental]

✖

starts an external session using the external evaluator sys, returning an external session object.

✖

starts the external evaluator specified by assoc.

✖
StartExternalSession[{"sys",opts}]

uses the options opts for the external evaluator.

✖
StartExternalSession[systype]

specifies that output from the external evaluator should be converted to the specified type.

✖

uses the database specified by ref to start a database session.

Details

  • 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".
  • FindExternalEvaluators gives a dataset 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 allclose all

Basic Examples  (3)Summary of the most common use cases

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-lketrq
Out[1]=1

Evaluate code in the session:

In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-m3pl17
Out[2]=2

Stop the session with DeleteObject:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-0rmxua

Start a session using Python Version 3:

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-cvhjs4
Out[1]=1

Verify the version:

In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-gbxbwc
Out[2]=2

End the session:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-oh8s2q

Start a new Python session in a provisioned environment:

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-j80han
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-jdl2g4
Out[2]=2

Scope  (16)Survey of the scope of standard use cases

Basic Uses  (2)

Multiple external sessions can be run simultaneously:

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-oyl4nd
Out[1]=1

Delete the session objects:

In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-3vzav6

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-e4v0la
Out[1]=1

Use the session for multiple calls to ExternalEvaluate:

In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-6wq5wr
In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-jvghn7
Out[3]=3

Stop the session with DeleteObject:

In[4]:=4
✖
https://wolfram.com/xid/0k7vpfug13i7m-g6r2hg

Session Options  (14)

"ReturnType"  (4)

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-wtbdnk
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-o6pe7m
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-v6kqn2
Out[3]=3

Delete the session objects:

In[4]:=4
✖
https://wolfram.com/xid/0k7vpfug13i7m-1rxkyc

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-4bqtee
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-5qg8yf
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-7plv6t
Out[3]=3

Delete the session objects:

In[4]:=4
✖
https://wolfram.com/xid/0k7vpfug13i7m-gw121v

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-blcv4
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-d3mosj
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-7m4kl8
Out[3]=3

Delete the session objects:

In[4]:=4
✖
https://wolfram.com/xid/0k7vpfug13i7m-vmx606

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-xsyvsz
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-4ns3rj
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-bqup95
Out[3]=3

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

In[4]:=4
✖
https://wolfram.com/xid/0k7vpfug13i7m-7459fm
In[5]:=5
✖
https://wolfram.com/xid/0k7vpfug13i7m-g5j12f
Out[5]=5
In[6]:=6
✖
https://wolfram.com/xid/0k7vpfug13i7m-cgvwh6
In[7]:=7
✖
https://wolfram.com/xid/0k7vpfug13i7m-6oe2ed
Out[7]=7
In[8]:=8
✖
https://wolfram.com/xid/0k7vpfug13i7m-ppsurx
In[9]:=9
✖
https://wolfram.com/xid/0k7vpfug13i7m-5rzuvf
Out[9]=9
In[10]:=10
✖
https://wolfram.com/xid/0k7vpfug13i7m-c8853f
In[11]:=11
✖
https://wolfram.com/xid/0k7vpfug13i7m-0o9wgp
Out[11]=11

Delete the session objects:

In[12]:=12
✖
https://wolfram.com/xid/0k7vpfug13i7m-e4wcwr

"Evaluator"  (3)

Evaluate code using a specified "Evaluator":

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-l8qzu4
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-eafuyy
Out[2]=2

Delete the session objects:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-rm9a1x

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-jqhheo
Out[1]=1

Use the session to evaluate the code:

In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-j25eq
In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-q9c0ta

Delete the session objects:

In[4]:=4
✖
https://wolfram.com/xid/0k7vpfug13i7m-5vb73

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-gp06yk
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-vnifkx
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-gj1i7c
In[4]:=4
✖
https://wolfram.com/xid/0k7vpfug13i7m-xbwrlg
Out[4]=4

Delete the session objects:

In[5]:=5
✖
https://wolfram.com/xid/0k7vpfug13i7m-0lzjia

"Name"  (1)

Register an evaluator using a name:

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-7fgail
Out[1]=1

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

In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-2j03ng
Out[2]=2

Use the session:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-rp923e
Out[3]=3

Close the session:

In[4]:=4
✖
https://wolfram.com/xid/0k7vpfug13i7m-b0muyh

"ID"  (1)

Start an evaluator with a given "ID":

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-22lijw
Out[1]=1

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

In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-g83gz9
Out[2]=2

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

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-h5bap1
Out[3]=3

Close the session:

In[4]:=4
✖
https://wolfram.com/xid/0k7vpfug13i7m-13g1pr

"SessionProlog"  (2)

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-3lqh5y
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-g6q0rr
Out[2]=2

Delete the session objects:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-dxyfy3

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-wzkokn
Out[1]=1

Evaluate a function from the imported library:

In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-m5fo6c
Out[2]=2

Delete the session object:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-lf43oa

"SessionEpilog"  (1)

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-6wdtvl
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-ly2bwc
Out[2]=2

Delete the session object:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-17t2qq

"Prolog"  (1)

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-prbb8s
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-2cvfk4

Delete the session object:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-swdxll

"Epilog"  (1)

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

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-qxywm3
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-zo7x91
Out[2]=2

Delete the session object:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-nfqye0

Properties & Relations  (4)Properties of the function, and connections to other functions

Each session runs in its own process:

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-rx95mp
Out[1]=1

The process IDs for each session are different:

In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-xu7nfv
Out[2]=2

Delete the session objects:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-x1igta

If only the language is specified, the first evaluator returned by FindExternalEvaluators is used:

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-x5zduw
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-qnuhi0
Out[2]=2

Stop the session:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-cebyxe

Start a database session:

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-gw71y4
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-pcce2y
Out[2]=2

Run a query:

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-me9icm
Out[3]=3

Manually close the session:

In[4]:=4
✖
https://wolfram.com/xid/0k7vpfug13i7m-gzoero

External language cells implicitly call StartExternalSession:

In[1]:=1
✖
https://wolfram.com/xid/0k7vpfug13i7m-igr15a
Out[1]=1
x=2

A new session has been started:

In[2]:=2
✖
https://wolfram.com/xid/0k7vpfug13i7m-r6exto
Out[2]=2

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

x*x
Out[6]=6

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

In[3]:=3
✖
https://wolfram.com/xid/0k7vpfug13i7m-uq1fg7
Wolfram Research (2017), StartExternalSession, Wolfram Language function, https://reference.wolfram.com/language/ref/StartExternalSession.html (updated 2024).
✖
Wolfram Research (2017), StartExternalSession, Wolfram Language function, https://reference.wolfram.com/language/ref/StartExternalSession.html (updated 2024).

Text

Wolfram Research (2017), StartExternalSession, Wolfram Language function, https://reference.wolfram.com/language/ref/StartExternalSession.html (updated 2024).

✖
Wolfram Research (2017), StartExternalSession, Wolfram Language function, https://reference.wolfram.com/language/ref/StartExternalSession.html (updated 2024).

CMS

Wolfram Language. 2017. "StartExternalSession." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2024. https://reference.wolfram.com/language/ref/StartExternalSession.html.

✖
Wolfram Language. 2017. "StartExternalSession." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2024. https://reference.wolfram.com/language/ref/StartExternalSession.html.

APA

Wolfram Language. (2017). StartExternalSession. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/StartExternalSession.html

✖
Wolfram Language. (2017). StartExternalSession. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/StartExternalSession.html

BibTeX

@misc{reference.wolfram_2025_startexternalsession, author="Wolfram Research", title="{StartExternalSession}", year="2024", howpublished="\url{https://reference.wolfram.com/language/ref/StartExternalSession.html}", note=[Accessed: 25-March-2025 ]}

✖
@misc{reference.wolfram_2025_startexternalsession, author="Wolfram Research", title="{StartExternalSession}", year="2024", howpublished="\url{https://reference.wolfram.com/language/ref/StartExternalSession.html}", note=[Accessed: 25-March-2025 ]}

BibLaTeX

@online{reference.wolfram_2025_startexternalsession, organization={Wolfram Research}, title={StartExternalSession}, year={2024}, url={https://reference.wolfram.com/language/ref/StartExternalSession.html}, note=[Accessed: 25-March-2025 ]}

✖
@online{reference.wolfram_2025_startexternalsession, organization={Wolfram Research}, title={StartExternalSession}, year={2024}, url={https://reference.wolfram.com/language/ref/StartExternalSession.html}, note=[Accessed: 25-March-2025 ]}