Create Cloud TPU VMs

You create TPU VMs using the Create Node API, the queued resources API, or Google Kubernetes Engine (GKE).

You call the Create Node API when you run the gcloud compute tpus tpu-vm create command using the Google Cloud CLI and when you create a TPU VM using the Google Cloud console. When you use the Create Node API, the system processes your request immediately. If there is not enough capacity to fulfill your request, the request fails.

We recommend creating TPU VMs using the queued resources API. When you create a TPU VM using the queued resource API, the Cloud TPU service adds your queued resource request to a queue that the service maintains. When the requested resource becomes available, the service assigns it to your Google Cloud project for your immediate and exclusive use. For more information, see Manage queued resources .

If you want to use Google Kubernetes Engine (GKE) to manage TPU resources, first, create a GKE cluster. Then, add node pools containing TPU slices to your cluster. For more information, see About TPUs in GKE .

Prerequisites

Complete the following prerequisites:

Create a Google Cloud project for your TPUs as described in Set up a Google Cloud project for TPUs .
Determine your TPU requirements as described in Plan your Cloud TPU resources .
If you're using one of the Cloud Client Libraries , follow the setup instructions for the language you're using:
- Python
- Java
- Node.js

Set environment variables for creating a v5e TPU with eight chips. The following examples use a v5e TPU with eight chips. You can specify a different accelerator type and version. See TPU versions for more information.

   
 export 
  
 TPU_NAME 
 = 
 your-tpu-name 
  
 export 
  
 PROJECT_ID 
 = 
 your-project 
  
 export 
  
 ZONE 
 = 
 us-central1-a 
  
 export 
  
 ACCELERATOR_TYPE 
 = 
 v5litepod-8 
  
 export 
  
 VERSION 
 = 
 v2-alpha-tpuv5-lite

Create a Cloud TPU using the Create Node API

You create a Cloud TPU using gcloud , the Google Cloud console, or the Cloud TPU API.

When creating a Cloud TPU, specify the TPU software version (also called runtime version). To determine which software version to use, see TPU software versions .

Also, specify the number of TensorCores or TPU chips for the TPU configuration you are using. For more information, see the section for your TPU version in System architecture .

gcloud

Use the gcloud compute tpus tpu-vm create command to create a TPU using the Create Node API. See External and internal IP addresses to configure specific internal or external IP addresses.

The following command creates a v5e TPU VM with 8 TPU chips:

gcloud  
compute  
tpus  
tpu-vm  
create  
 $TPU_NAME 
  
 \ 
  
--project = 
 $PROJECT_ID 
  
--zone = 
 $ZONE 
  
 \ 
  
--accelerator-type = 
 $ACCELERATOR_TYPE 
  
 \ 
  
--version = 
 $VERSION

Command flag descriptions

zone: The zone where you create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you create. For more information about supported accelerator types for each TPU version, see TPU versions .
version: The TPU software version.

Console

These instructions create a v5e TPU VM with 8 TPU chips:

In the Google Cloud console, go to the TPUspage:

Go to TPUs
Click Create TPU.
In the Namefield, enter a name for your TPU.
In the Zonefield, select the zone where you create the TPU.
In the TPU typefield, select an accelerator type. The accelerator type specifies the version and size of the Cloud TPU you create. For more information about supported accelerator types for each TPU version, see TPU versions .
In the TPU software versionfield, select a software version. When creating a Cloud TPU VM, the TPU software version specifies the version of the TPU runtime to install. For more information, see TPU software versions .
Click Createto create your resources.

curl

The following command uses curl to create a v5e TPU VM with 8 TPU chips.

curl  
-X  
POST  
-H  
 "Authorization: Bearer 
 $( 
gcloud  
auth  
print-access-token ) 
 " 
  
-H  
 "Content-Type: application/json" 
  
-d  
 "{accelerator_type: 
 $ACCELERATOR_TYPE 
 , \ 
 runtime_version:' 
 $VERSION 
 ', \ 
 network_config: {enable_external_ips: true}, \ 
 shielded_instance_config: { enable_secure_boot: true }}" 
  
 \ 
https://tpu.googleapis.com/v2/projects/ $PROJECT_ID 
/locations/ $ZONE 
/nodes?node_id = 
 $TPU_NAME

Required fields

runtime_version: The Cloud TPU runtime version that you use.
project-id: The name of your enrolled Google Cloud project.
zone: The zone where you create your Cloud TPU.
node_name: The name of the TPU VM you create.

Java

This code example creates a v5e TPU VM with 8 TPU chips using the Cloud TPU API in Java.

To authenticate to Cloud TPU, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  import 
  
 com.google.api.gax.longrunning. OperationTimedPollAlgorithm 
 
 ; 
 import 
  
 com.google.api.gax.retrying. RetrySettings 
 
 ; 
 import 
  
 com.google.cloud.tpu.v2. CreateNodeRequest 
 
 ; 
 import 
  
 com.google.cloud.tpu.v2. Node 
 
 ; 
 import 
  
 com.google.cloud.tpu.v2. TpuClient 
 
 ; 
 import 
  
 com.google.cloud.tpu.v2. TpuSettings 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 import 
  
 java.util.concurrent.ExecutionException 
 ; 
 import 
  
 org.threeten.bp.Duration 
 ; 
 public 
  
 class 
 CreateTpuVm 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 [] 
  
 args 
 ) 
  
 throws 
  
 IOException 
 , 
  
 ExecutionException 
 , 
  
 InterruptedException 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample. 
  
 // Project ID or project number of the Google Cloud project you want to create a node. 
  
 String 
  
 projectId 
  
 = 
  
 "YOUR_PROJECT_ID" 
 ; 
  
 // The zone in which to create the TPU. 
  
 // For more information about supported TPU types for specific zones, 
  
 // see https://cloud.google.com/tpu/docs/regions-zones 
  
 String 
  
 zone 
  
 = 
  
 "europe-west4-a" 
 ; 
  
 // The name for your TPU. 
  
 String 
  
 nodeName 
  
 = 
  
 "YOUR_TPU_NAME" 
 ; 
  
 // The accelerator type that specifies the version and size of the Cloud TPU you want to create. 
  
 // For more information about supported accelerator types for each TPU version, 
  
 // see https://cloud.google.com/tpu/docs/system-architecture-tpu-vm#versions. 
  
 String 
  
 tpuType 
  
 = 
  
 "v2-8" 
 ; 
  
 // Software version that specifies the version of the TPU runtime to install. 
  
 // For more information see https://cloud.google.com/tpu/docs/runtimes 
  
 String 
  
 tpuSoftwareVersion 
  
 = 
  
 "v2-tpuv5-litepod" 
 ; 
  
 createTpuVm 
 ( 
 projectId 
 , 
  
 zone 
 , 
  
 nodeName 
 , 
  
 tpuType 
 , 
  
 tpuSoftwareVersion 
 ); 
  
 } 
  
 // Creates a TPU VM with the specified name, zone, accelerator type, and version. 
  
 public 
  
 static 
  
  Node 
 
  
 createTpuVm 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 zone 
 , 
  
 String 
  
 nodeName 
 , 
  
 String 
  
 tpuType 
 , 
  
 String 
  
 tpuSoftwareVersion 
 ) 
  
 throws 
  
 IOException 
 , 
  
 ExecutionException 
 , 
  
 InterruptedException 
  
 { 
  
 // With these settings the client library handles the Operation's polling mechanism 
  
 // and prevent CancellationException error 
  
  TpuSettings 
 
 . 
 Builder 
  
 clientSettings 
  
 = 
  
  TpuSettings 
 
 . 
 newBuilder 
 (); 
  
 clientSettings 
  
 . 
 createNodeOperationSettings 
 () 
  
 . 
 setPollingAlgorithm 
 ( 
  
  OperationTimedPollAlgorithm 
 
 . 
 create 
 ( 
  
  RetrySettings 
 
 . 
 newBuilder 
 () 
  
 . 
  setInitialRetryDelay 
 
 ( 
 Duration 
 . 
 ofMillis 
 ( 
 5000L 
 )) 
  
 . 
  setRetryDelayMultiplier 
 
 ( 
 1.5 
 ) 
  
 . 
  setMaxRetryDelay 
 
 ( 
 Duration 
 . 
 ofMillis 
 ( 
 45000L 
 )) 
  
 . 
  setInitialRpcTimeout 
 
 ( 
 Duration 
 . 
 ZERO 
 ) 
  
 . 
  setRpcTimeoutMultiplier 
 
 ( 
 1.0 
 ) 
  
 . 
  setMaxRpcTimeout 
 
 ( 
 Duration 
 . 
 ZERO 
 ) 
  
 . 
  setTotalTimeout 
 
 ( 
 Duration 
 . 
 ofHours 
 ( 
 24L 
 )) 
  
 . 
 build 
 ())); 
  
 // Initialize client that will be used to send requests. This client only needs to be created 
  
 // once, and can be reused for multiple requests. 
  
 try 
  
 ( 
  TpuClient 
 
  
 tpuClient 
  
 = 
  
  TpuClient 
 
 . 
 create 
 ( 
 clientSettings 
 . 
 build 
 ())) 
  
 { 
  
 String 
  
 parent 
  
 = 
  
 String 
 . 
 format 
 ( 
 "projects/%s/locations/%s" 
 , 
  
 projectId 
 , 
  
 zone 
 ); 
  
  Node 
 
  
 tpuVm 
  
 = 
  
  Node 
 
 . 
 newBuilder 
 () 
  
 . 
 setName 
 ( 
 nodeName 
 ) 
  
 . 
 setAcceleratorType 
 ( 
 tpuType 
 ) 
  
 . 
 setRuntimeVersion 
 ( 
 tpuSoftwareVersion 
 ) 
  
 . 
 build 
 (); 
  
  CreateNodeRequest 
 
  
 request 
  
 = 
  
  CreateNodeRequest 
 
 . 
 newBuilder 
 () 
  
 . 
 setParent 
 ( 
 parent 
 ) 
  
 . 
 setNodeId 
 ( 
 nodeName 
 ) 
  
 . 
 setNode 
 ( 
 tpuVm 
 ) 
  
 . 
 build 
 (); 
  
 return 
  
 tpuClient 
 . 
  createNodeAsync 
 
 ( 
 request 
 ). 
  get 
 
 (); 
  
 } 
  
 } 
 }

// Import the TPUClient // TODO(developer): Uncomment below line before running the sample. // const {TpuClient} = require('@google-cloud/tpu').v2; const { Node , NetworkConfig } = require ( ' @google-cloud/tpu ' ). protos . google . cloud . tpu . v2 ; // Instantiate a tpuClient // TODO(developer): Uncomment below line before running the sample. // tpuClient = new TpuClient(); // TODO(developer): Update below line before running the sample. // Project ID or project number of the Google Cloud project you want to create a node. const projectId = await tpuClient . getProjectId (); // The name of the network you want the TPU node to connect to. The network should be assigned to your project. const networkName = 'compute-tpu-network' ; // The region of the network, that you want the TPU node to connect to. const region = 'europe-west4' ; // The name for your TPU. const nodeName = 'node-name-1' ; // The zone in which to create the TPU. // For more information about supported TPU types for specific zones, // see https://cloud.google.com/tpu/docs/regions-zones const zone = 'europe-west4-a' ; // The accelerator type that specifies the version and size of the Cloud TPU you want to create. // For more information about supported accelerator types for each TPU version, // see https://cloud.google.com/tpu/docs/system-architecture-tpu-vm#versions. const tpuType = 'v5litepod-4' ; // Software version that specifies the version of the TPU runtime to install. For more information, // see https://cloud.google.com/tpu/docs/runtimes const tpuSoftwareVersion = 'v2-tpuv5-litepod' ; async function callCreateTpuVM () { // Create a node const node = new Node ({ name : nodeName , zone , acceleratorType : tpuType , runtimeVersion : tpuSoftwareVersion , // Define network networkConfig : new NetworkConfig ({ enableExternalIps : true , network : `projects/ ${ projectId } /global/networks/ ${ networkName } ` , subnetwork : `projects/ ${ projectId } /regions/ ${ region } /subnetworks/ ${ networkName } ` , }), }); const parent = `projects/ ${ projectId } /locations/ ${ zone } ` ; const request = { parent , node , nodeId : nodeName }; const [ operation ] = await tpuClient . createNode ( request ); // Wait for the create operation to complete. const [ response ] = await operation . promise (); console . log ( `TPU VM: ${ nodeName } created.` ); return response ; } return await callCreateTpuVM ();

from google.cloud import tpu_v2 # TODO(developer): Update and un-comment below lines # project_id = "your-project-id" # zone = "us-central1-a" # tpu_name = "tpu-name" # tpu_type = "v5litepod-4" # runtime_version = "v2-tpuv5-litepod" # Create a TPU node node = tpu_v2 . Node () node . accelerator_type = tpu_type # To see available runtime version use command: # gcloud compute tpus versions list --zone={ZONE} node . runtime_version = runtime_version request = tpu_v2 . CreateNodeRequest ( parent = f "projects/ { project_id } /locations/ { zone } " , node_id = tpu_name , node = node , ) # Create a TPU client client = tpu_v2 . TpuClient () operation = client . create_node ( request = request ) print ( "Waiting for operation to complete..." ) response = operation . result () print ( response ) # Example response: # name: "projects/[project_id]/locations/[zone]/nodes/my-tpu" # accelerator_type: "v5litepod-4" # state: READY # ...

Run a startup script

You run a startup script on your TPU VM by specifying the --metadata startup-script flag when you create the TPU VM.

gcloud

This command creates a TPU VM and specifies a startup script.

gcloud  
compute  
tpus  
tpu-vm  
create  
 $TPU_NAME 
  
 \ 
  
--zone = 
 $ZONE 
  
 \ 
  
--accelerator-type = 
 $ACCELERATOR_TYPE 
  
 \ 
  
--version = 
 $VERSION 
  
 \ 
  
--metadata  
startup-script = 
 '#! /bin/bash 
 pip3 install numpy 
 EOF'

Java

This code example creates a TPU VM and specifies a startup script in Java.

To authenticate to Cloud TPU, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  import 
  
 com.google.cloud.tpu.v2. CreateNodeRequest 
 
 ; 
 import 
  
 com.google.cloud.tpu.v2. Node 
 
 ; 
 import 
  
 com.google.cloud.tpu.v2. TpuClient 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 import 
  
 java.util.HashMap 
 ; 
 import 
  
 java.util.Map 
 ; 
 import 
  
 java.util.concurrent.ExecutionException 
 ; 
 public 
  
 class 
 CreateTpuVmWithStartupScript 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 [] 
  
 args 
 ) 
  
 throws 
  
 IOException 
 , 
  
 ExecutionException 
 , 
  
 InterruptedException 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample. 
  
 // Project ID or project number of the Google Cloud project you want to create a node. 
  
 String 
  
 projectId 
  
 = 
  
 "YOUR_PROJECT_ID" 
 ; 
  
 // The zone in which to create the TPU. 
  
 // For more information about supported TPU types for specific zones, 
  
 // see https://cloud.google.com/tpu/docs/regions-zones 
  
 String 
  
 zone 
  
 = 
  
 "us-central1-a" 
 ; 
  
 // The name for your TPU. 
  
 String 
  
 nodeName 
  
 = 
  
 "YOUR_TPU_NAME" 
 ; 
  
 // The accelerator type that specifies the version and size of the Cloud TPU you want to create. 
  
 // For more information about supported accelerator types for each TPU version, 
  
 // see https://cloud.google.com/tpu/docs/system-architecture-tpu-vm#versions. 
  
 String 
  
 acceleratorType 
  
 = 
  
 "v5litepod-4" 
 ; 
  
 // Software version that specifies the version of the TPU runtime to install. 
  
 // For more information, see https://cloud.google.com/tpu/docs/runtimes 
  
 String 
  
 tpuSoftwareVersion 
  
 = 
  
 "v2-tpuv5-litepod" 
 ; 
  
 createTpuVmWithStartupScript 
 ( 
 projectId 
 , 
  
 zone 
 , 
  
 nodeName 
 , 
  
 acceleratorType 
 , 
  
 tpuSoftwareVersion 
 ); 
  
 } 
  
 // Create a TPU VM with a startup script. 
  
 public 
  
 static 
  
  Node 
 
  
 createTpuVmWithStartupScript 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 zone 
 , 
  
 String 
  
 nodeName 
 , 
  
 String 
  
 acceleratorType 
 , 
  
 String 
  
 tpuSoftwareVersion 
 ) 
  
 throws 
  
 IOException 
 , 
  
 ExecutionException 
 , 
  
 InterruptedException 
  
 { 
  
 // Initialize client that will be used to send requests. This client only needs to be created 
  
 // once, and can be reused for multiple requests. 
  
 try 
  
 ( 
  TpuClient 
 
  
 tpuClient 
  
 = 
  
  TpuClient 
 
 . 
 create 
 ()) 
  
 { 
  
 String 
  
 parent 
  
 = 
  
 String 
 . 
 format 
 ( 
 "projects/%s/locations/%s" 
 , 
  
 projectId 
 , 
  
 zone 
 ); 
  
 String 
  
 startupScriptContent 
  
 = 
  
 "#!/bin/bash\necho \"Hello from the startup script!\"" 
 ; 
  
 // Add startup script to metadata 
  
 Map<String 
 , 
  
 String 
>  
 metadata 
  
 = 
  
 new 
  
 HashMap 
<> (); 
  
 metadata 
 . 
 put 
 ( 
 "startup-script" 
 , 
  
 startupScriptContent 
 ); 
  
  Node 
 
  
 tpuVm 
  
 = 
  
  Node 
 
 . 
 newBuilder 
 () 
  
 . 
 setName 
 ( 
 nodeName 
 ) 
  
 . 
 setAcceleratorType 
 ( 
 acceleratorType 
 ) 
  
 . 
 setRuntimeVersion 
 ( 
 tpuSoftwareVersion 
 ) 
  
 . 
  putAllMetadata 
 
 ( 
 metadata 
 ) 
  
 . 
 build 
 (); 
  
  CreateNodeRequest 
 
  
 request 
  
 = 
  
  CreateNodeRequest 
 
 . 
 newBuilder 
 () 
  
 . 
 setParent 
 ( 
 parent 
 ) 
  
 . 
 setNodeId 
 ( 
 nodeName 
 ) 
  
 . 
 setNode 
 ( 
 tpuVm 
 ) 
  
 . 
 build 
 (); 
  
 return 
  
 tpuClient 
 . 
  createNodeAsync 
 
 ( 
 request 
 ). 
 get 
 (); 
  
 } 
  
 } 
 }

// Import the TPUClient // TODO(developer): Uncomment below line before running the sample. // const {TpuClient} = require('@google-cloud/tpu').v2; const { Node , NetworkConfig } = require ( ' @google-cloud/tpu ' ). protos . google . cloud . tpu . v2 ; // Instantiate a tpuClient // TODO(developer): Uncomment below line before running the sample. // tpuClient = new TpuClient(); // TODO(developer): Update these variables before running the sample. // Project ID or project number of the Google Cloud project you want to create a node. const projectId = await tpuClient . getProjectId (); // The name of the network you want the TPU node to connect to. The network should be assigned to your project. const networkName = 'compute-tpu-network' ; // The region of the network, that you want the TPU node to connect to. const region = 'europe-west4' ; // The name for your TPU. const nodeName = 'node-name-1' ; // The zone in which to create the TPU. // For more information about supported TPU types for specific zones, // see https://cloud.google.com/tpu/docs/regions-zones const zone = 'europe-west4-a' ; // The accelerator type that specifies the version and size of the Cloud TPU you want to create. // For more information about supported accelerator types for each TPU version, // see https://cloud.google.com/tpu/docs/system-architecture-tpu-vm#versions. const tpuType = 'v5litepod-4' ; // Software version that specifies the version of the TPU runtime to install. For more information, // see https://cloud.google.com/tpu/docs/runtimes const tpuSoftwareVersion = 'v2-tpuv5-litepod' ; async function callCreateTpuVMStartupScript () { // Create a node const node = new Node ({ name : nodeName , zone , acceleratorType : tpuType , runtimeVersion : tpuSoftwareVersion , // Define network networkConfig : new NetworkConfig ({ enableExternalIps : true , network : `projects/ ${ projectId } /global/networks/ ${ networkName } ` , subnetwork : `projects/ ${ projectId } /regions/ ${ region } /subnetworks/ ${ networkName } ` , }), metadata : { // The script updates numpy to the latest version and logs the output to a file. 'startup-script' : `#!/bin/bash echo "Hello World" > /var/log/hello.log sudo pip3 install --upgrade numpy >> /var/log/hello.log 2>&1` , }, }); const parent = `projects/ ${ projectId } /locations/ ${ zone } ` ; const request = { parent , node , nodeId : nodeName }; const [ operation ] = await tpuClient . createNode ( request ); // Wait for the create operation to complete. const [ response ] = await operation . promise (); console . log ( JSON . stringify ( response )); return response ; } return await callCreateTpuVMStartupScript ();

from google.cloud import tpu_v2 # TODO(developer): Update and un-comment below lines # project_id = "your-project-id" # zone = "us-central1-a" # tpu_name = "tpu-name" # tpu_type = "v5litepod-4" # runtime_version = "v2-tpuv5-litepod" node = tpu_v2 . Node () node . accelerator_type = tpu_type node . runtime_version = runtime_version # This startup script updates numpy to the latest version and logs the output to a file. metadata = { "startup-script" : """#!/bin/bash echo "Hello World" > /var/log/hello.log sudo pip3 install --upgrade numpy >> /var/log/hello.log 2>&1 """ } # Adding metadata with startup script to the TPU node. node . metadata = metadata # Enabling external IPs for internet access from the TPU node. node . network_config = tpu_v2 . NetworkConfig ( enable_external_ips = True ) request = tpu_v2 . CreateNodeRequest ( parent = f "projects/ { project_id } /locations/ { zone } " , node_id = tpu_name , node = node , ) client = tpu_v2 . TpuClient () operation = client . create_node ( request = request ) print ( "Waiting for operation to complete..." ) response = operation . result () print ( response . metadata ) # Example response: # {'startup-script': '#!/bin/bash\n echo "Hello World" > /var/log/hello.log\n # ...

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License , and code samples are licensed under the Apache 2.0 License . For details, see the Google Developers Site Policies . Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-02 UTC.

Create Cloud TPU VMs

Prerequisites

Create a Cloud TPU using the Create Node API

gcloud

Command flag descriptions

Console

curl

Required fields

Java

Node.js

Python

Run a startup script

gcloud

Java

Node.js

Python

What's next