wolframresearch/wolframengine repository overview

⁠Quick Reference

• Maintained by: Wolfram Research⁠
• Where to get help: Wolfram Community⁠
• License:
  • Please note that the Wolfram Engine Community Edition is licensed software, subject to the terms of use⁠ listed on the Wolfram Research website.
  • To use the Wolfram Engine, you will need to sign up for a (free) developer license⁠. The developer license requires the creation of a Wolfram ID and acceptance of the terms of use.

⁠Supported Tags

• 14.3, 14.3.0, latest

⁠Image Variants

⁠wolframresearch/wolframengine:<version>

Base: ubuntu:22.04⁠
This is the standard image, containing only the stock Wolfram Engine and the WolframScript⁠ command-line wrapper.

⁠wolframresearch/wolframengine:<version>-cuda

Base: nvidia/cuda:10.2-base-ubuntu18.04⁠

The CUDA image variant is currently unsupported.

This image includes the standard Wolfram Engine and WolframScript, plus the MXNetResources paclet required to make use of GPU acceleration with the machine learning and neural network functionality of the Wolfram Language. This image requires a supported NVIDIA GPU⁠ and the NVIDIA container runtime⁠. This image may be updated between Wolfram Engine releases if a new version of the MXNetResources paclet is released.

⁠Introduction

The Wolfram Engine Docker image allows you to run the Wolfram Language in either interactive or scripting mode.

The Wolfram Engine gives you access to the Wolfram Language. See:

• The Wolfram Language home page⁠ for an overview of the Wolfram Language
• The Wolfram Language Fast Introduction for Programmers⁠, a getting-started tutorial
• The Wolfram Language Documentation Center⁠ for full reference documentation

⁠Activating and Running the Wolfram Engine

There are two licensing methods available for use with the Wolfram Engine. You may choose either one based on the needs of your application.

1. Node-locked licensing⁠: This is the standard licensing method used with the Wolfram Engine. The Wolfram Engine kernel is launched interactively on the command line, producing a Wolfram Account login prompt. After entering your Wolfram Account credentials, a mathpass file⁠ containing a device-specific activation password is written to disk (not to be confused with your account password). This method allows you to use a Wolfram Engine Community Edition⁠ license, but you are restricted to activating the Wolfram Engine on a limited number of machines (generally two). This approach may not be suitable for environments where containers may be scheduled to any of several physical or virtual nodes, such as Kubernetes or Docker Swarm clusters.
2. On-demand licensing⁠: This is a pay-as-you-go licensing method whereby Wolfram Engine usage is billed against your Wolfram Service Credits⁠ balance at a per-kernel-hour rate. This method allows you to run large numbers of concurrent Wolfram Engine kernels for pennies per kernel per hour, and to scale up and down in a cost-effective manner. This approach is not compatible with the Wolfram Engine Community Edition license, although you may use the starter Service Credits quota available with a free Wolfram Cloud Basic account for initial experimentation before purchasing more Service Credits or a paid Wolfram|One⁠ subscription.

⁠Activate Using Node-Locked Licensing

⁠1. Run the Docker image to activate the Wolfram Engine

Visit the Wolfram Research website first to get a license⁠ for Wolfram Engine Community Edition. You will be asked to sign up for a Wolfram ID and to accept the terms of use.

To activate the Wolfram Engine, you need to run a Docker container in interactive mode. Use your own Wolfram ID in place of [email protected], and type your own password at the password prompt.

After the Wolfram Engine activates, type "$PasswordFile" at the In[1] prompt and press Enter. The output will show you the location of the password file. Next, at the In[2] prompt, type "$PasswordFile // FilePrint" to print the content of the password file. Next, at the In[3] prompt, type "Quit" and press Enter to exit the Wolfram Engine.

> docker run -it wolframresearch/wolframengine
The Wolfram Engine requires one-time activation on this computer.

Visit https://wolfram.com/developer-license to get your free license.

Wolfram ID: [email protected]
Password:
Wolfram Engine activated. See https://www.wolfram.com/wolframscript/ for more information.
Wolfram Language 12.2.0 Engine for Linux x86 (64-bit)
Copyright 1988-2020 Wolfram Research, Inc.

In[1]:= $PasswordFile

Out[1]= /home/wolframengine/.WolframEngine/Licensing/mathpass

In[2]:= $PasswordFile // FilePrint
1e1d781ed0a3    6520-03713-97466        4304-2718-2K5ATR        5095-179-696:2,0,8,8:80001:20190627

In[3]:= Quit

Because file system changes made within a container do not persist to the image with which the container was started, this password information is lost when you restart and run the image again. For this reason, you need to copy the password information to the host machine, where it can be stored persistently.

⁠2. Copy the password file to the host machine

On the host machine, create a Licensing directory that will hold the password file:

mkdir Licensing

With a text editor, create a file called mathpass and copy and paste the password (the output from In[2] shown in step 1) into it. Save the file. You should now have a file called mathpass in the Licensing directory, and this mathpass file should contain a single line with four fields. These four fields, for informational purposes, represent the machine name, a unique machine identifier, your activation key and the password.

⁠3. Run the Wolfram Engine using the password file

To launch the Wolfram Engine with the password file from the host machine, use the -v option to make the ./Licensing directory available to the Docker container under /usr/share/Mathematica/Licensing. If everything works correctly, you should now be able to launch this Docker container over and over, and you can use this as a starting point to customize things for your development project.

> docker run -it -v ./Licensing:/usr/share/Mathematica/Licensing wolframresearch/wolframengine

Wolfram Language 12.2.0 Engine for Linux x86 (64-bit)
Copyright 1988-2020 Wolfram Research, Inc.

In[1]:= $MachineName

Out[1]= 861d2b5cd33f

In[2]:= $Version

Out[2]= 12.2.0 for Linux x86 (64-bit) (December 12, 2020)

Alternatively, the docker commit command⁠ may be used to create a new image including the mathpass file created in a running container.

⁠Notes

• The password for Wolfram Engine Community Edition has an expiration date. When the actual date is close to the expiration date, the Wolfram Engine will automatically reactivate itself. However, you will need to copy the newer password from the $PasswordFile again to the host machine mathpass file (basically repeating steps 1 and 2 shown previously).
• Activating a Wolfram Engine Docker image uses up one of the two activation keys that were assigned to you when you signed up for the Wolfram Engine Community Edition license.

⁠Activate Using On-Demand Licensing

⁠1. Create a license entitlement

An on-demand license entitlement is a reusable key that can be used to activate one or more Wolfram Engine kernels. Creating an entitlement requires access to the Wolfram Language. If you do not have Wolfram Mathematica⁠, a Wolfram|One⁠ subscription or another Wolfram Language product, you can sign up for a free Wolfram Cloud Basic⁠ subscription and create an entitlement from within a cloud notebook.

Evaluate the CreateLicenseEntitlement function⁠ to create a new license entitlement linked to your Wolfram Account:

In[1]:= entitlement = CreateLicenseEntitlement[]

Out[1]= LicenseEntitlementObject[O-WSTD-DA42-GKX4Z6NR2DSZR, <|
    PolicyID -> WSTD, PolicyName -> Standard, BillingInterval -> 900 seconds,
    KernelCosts -> <|Standard -> 4. credits per hour, Parallel -> 4. credits per hour|>,
    KernelLimits -> <|Standard -> 1, Parallel -> 0|>,
    CreationDate -> DateObject[{2020, 12, 18, 10, 57, 40.}, Instant, Gregorian, -5.],
    ExpirationDate -> DateObject[{2020, 12, 25, 10, 57, 40.}, Instant, Gregorian, -5.],
    LicenseExpirationDuration -> 1 day 0. hours|>]

Obtain the entitlement ID as a string:

In[2]:= entitlement["EntitlementID"]

Out[2]= O-WSTD-DA42-GKX4Z6NR2DSZR

⁠2. Start the Wolfram Engine

To activate a Wolfram Engine kernel using an on-demand license entitlement, supply the entitlement ID to WolframScript⁠ via the -entitlement command-line option:

$ docker run -it wolframresearch/wolframengine wolframscript -entitlement O-WSTD-DA42-GKX4Z6NR2DSZR

Wolfram Language 12.2.0 Engine for Linux x86 (64-bit)
Copyright 1988-2020 Wolfram Research, Inc.

In[1]:= $MachineName

Out[1]= 652d62ac0fa4

In[2]:= $Version

Out[2]= 12.2.0 for Linux x86 (64-bit) (December 12, 2020)

(The entitlement ID can also be supplied to WolframScript via the WOLFRAMSCRIPT_ENTITLEMENTID environment variable.)

A charge was applied to your Service Credits balance when the kernel was launched, and your balance will continue to be charged regularly until the kernel is terminated. If you return to the Wolfram Language session in which you created the entitlement, you can request status properties of the entitlement:

In[3]:= entitlement["CreditsSpent"]

Out[3]= 1 credit

The count of active kernels has increased:

In[4]:= entitlement["StandardKernelActiveCount"]

Out[4]= 1

Consult the LicenseEntitlementObject documentation⁠ for more information on available properties of entitlement expressions.

⁠Notes

There are a few settings for the CreateLicenseEntitlement function⁠ that you may wish to change from their defaults:

• "StandardKernelLimit"/"ParallelKernelLimit": Defaults 1 and 0, respectively. These determine the maximum number of concurrently running Wolfram Engine kernels of each type that can be activated using the entitlement. "StandardKernelLimit" pertains to regular kernels, such as those launched via the command line, while "ParallelKernelLimit" pertains to parallel subkernels of the type started with LaunchKernels⁠ and parallel functions such as ParallelEvaluate⁠. Raise these values if you want to run more than one Wolfram Engine kernel at the same time.
• "LicenseExpiration": Defaults to 24 hours. This sets the maximum duration for which a Wolfram Engine kernel launched using the entitlement can run. With the default value of 24 hours, a kernel will be terminated after running for more than 24 hours. Raise this value if your application calls for long-running Wolfram Engine kernels.
• "EntitlementExpiration": Defaults to 7 days. This sets the expiration date of the license entitlement itself; that is, the date after which the entitlement's ID can no longer be used to activate new kernels. Raise this value if you want to use the same entitlement ID to launch multiple kernels over an extended period. This value can be set to a duration or an absolute date in the future.

Consult the documentation for the CreateLicenseEntitlement function⁠ for more information on available settings.