Run Code on Parallel Pools

What Is a Parallel Pool?

A parallel pool is a set of MATLAB^® workers on a compute cluster or desktop. By default, a parallel pool starts automatically when needed by parallel language features such as parfor. You can specify the default parallel environment in your parallel settings. The settings panel displays your default parallel environment when you select Parallel Settings in the Parallel menu. You can also specify the default parallel environment in the Parallel > Select Parallel Environment menu. Alternatively, you can choose parallel environment and pool size using parcluster and parpool respectively, on the MATLAB command line.

You can use the workers in a parallel pool interactively and the workers can communicate with each other during the lifetime of the job. You can view your parpool jobs in the Job Monitor. While these pool workers are reserved for your interactive use, they are not available to other users.

In MATLAB, a parallel pool is represented by a parallel.Pool object. You can only create a parallel pool from one parallel environment or profile at a time, but you can partition the pool into multiple pools, allowing for more flexible resource allocation. To learn more, see Partition Parallel Pools to Optimize Resource Use.

Before R2025a: You can have only one parallel pool at a time from a MATLAB client session.

Automatically Start and Stop a Parallel Pool

By default, a parallel pool starts automatically when needed by certain parallel language features. Many functions can automatically start a parallel pool, including:

• parfor

• spmd

• distributed

• Composite

• parfeval

• parfevalOnAll

• gcp

• mapreduce

• mapreducer

• tall

• ticBytes and tocBytes

Your parallel settings specify which parallel environment the pool runs on. To access your settings, on the Home tab, in the Environment section, select Parallel > Parallel Settings.

In your parallel settings, you can turn off the option for the pool to open or close automatically. If you turn off the option to open a pool automatically and you use any Parallel Computing Toolbox™ functionality without an open parallel pool, your code runs on the client.

Alternative Ways to Start and Stop Pools

If you choose not to have the pool open automatically, you can control the pool with the following techniques.

Control the Parallel Pool from the MATLAB Desktop

You can use the parallel status indicator in the lower left corner of the MATLAB desktop to start a parallel pool manually.

In MATLAB Online, the parallel status indicator is not visible by default. You must start a parallel pool first by using parpool or any of the functions that automatically start a parallel pool.

Click the indicator icon, and select Start Parallel Pool. The pool parallel environment is specified by your default parallel environment. Your default parallel environment is indicated by a check mark on the Parallel > Select Parallel Environment menu.

The parallel indicator menu options are different when a pool is running. You can:

• View the number of workers and the parallel environment the pool is running on

• Change the time until automatic shut-down

• Shut down the parallel pool

To stop a pool, you can also select Shut Down Parallel Pool.

Programming Interface

Start a Parallel Pool.  You can start and stop a parallel pool programmatically by using default settings or specifying alternatives.

To open a parallel pool based on your default settings:

parpool

To open a pool of a specific size:

parpool(4)

To use a parallel environment other than your default and specify where the pool runs:

parpool('MyProfile',4)

You can run a parallel pool on different parallel environments. For more information, see Choose Between Thread-Based and Process-Based Environments.

Shut Down a Parallel Pool.  To get the current parallel pool and use that object when you want to shut down the pool:

p = gcp;
delete(p)

Ensure That No Parallel Pool Is Running.  When you issue the command gcp without arguments, you might inadvertently open a pool. To avoid this problem:

delete(gcp('nocreate'))

Note

To stop a parallel pool while it is starting, press Ctrl+C or Ctrl+Break. On Apple macOS, you also can use Command. (the Command key and the period key).

Factors That Affect Pool Size

Parallel Computing Toolbox can support parallel pools with up to 2000 workers. When you create a parallel pool, the values of the NumWorkers and PreferredPoolNumWorkers profile properties affect the size of the parallel pool you get.

NumWorkers Property

The NumWorkers property is a hard limit on the number of workers available to the cluster or local machine.

• For MATLAB Job Scheduler clusters, the software determines the NumWorkers property value from the number of workers running in the cluster.

• For third-party scheduler clusters and the local machine Processes and Threads, you can specify the NumWorkers property value in the profile.

You cannot create a parallel pool larger than the NumWorkers property value.

PreferredPoolNumWorkers Property

The PreferredPoolNumWorkers property specifies a preference for the size of the pools the software creates with the profile. It is not a requirement or a request for a specific number of workers. The default value for the PreferredPoolNumWorkers property depends on the parallel environment. You can modify this value in the profile. The following is a list of parallel environments and their default PreferredPoolNumWorkers values:

• MATLAB Job Scheduler, shared cloud, and third-party scheduler clusters — 32

• Personal cloud clusters — Inf

• Local machine Processes — Inf (since R2023b)

  In R2023a: The default value is the NumWorkers property value.

• Local machine Threads — Inf (since R2025a)

Pool Creation Technique

The NumWorkers and PreferredPoolNumWorkers property values in combination with the technique you use to create the pool determine actual size of your parallel pool.

Pool Creation Technique	Actual Pool Size
You have automatic pool creation turned on, and you run a function that can automatically start a pool. You start a parallel pool manually using the parallel status indicator in the lower left corner of the MATLAB desktop You call the parpool function without specifying a pool size argument.	MATLAB uses the profile PreferredPoolNumWorkers property value to determine the maximum number of workers in the pool. If MATLAB cannot start a pool with as many workers as specified in the PreferredPoolNumWorkers property, you get a smaller pool without any errors. The pool size cannot exceed the NumWorkers value.
You run the parpool function and specify the pool size as an integer.	MATLAB attempts to start a pool with the exact number of workers you request. If the specified value does not exceed the NumWorkers property value, you get a pool with the specified number of workers. If the specified value exceeds the NumWorkers property value, MATLAB throws an error.
You run the parpool function and specify the pool size as a range of integers.	MATLAB attempts to create a pool with the largest possible value within that range without exceeding the NumWorkers property value. If the lower bound of the range is greater than the NumWorkers property value, MATLAB throws an error. If the upper bound of the range exceeds the NumWorkers property value, you get the largest pool size possible up to the NumWorkers property value.

Precedence for Parallel Environment Selection

For selection of the parallel environment on which the pool runs, precedence is determined by the following:

1. The parpool resources argument overrides the default profile setting and uses the parallel environment identified by the profile "MyProfile".

   p = parpool("MyProfile");

2. The parallel environment is specified in the default profile.

   p = parpool;