Use StartInstances with an Amazon SDK or CLI - Amazon Elastic Compute Cloud
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Use StartInstances with an Amazon SDK or CLI

The following code examples show how to use StartInstances.

Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:

.NET
Amazon SDK for .NET
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

/// <summary> /// Start an EC2 instance. /// </summary> /// <param name="ec2InstanceId">The instance Id of the Amazon EC2 instance /// to start.</param> /// <returns>Async task.</returns> public async Task StartInstances(string ec2InstanceId) { try { var request = new StartInstancesRequest { InstanceIds = new List<string> { ec2InstanceId }, }; await _amazonEC2.StartInstancesAsync(request); Console.Write("Waiting for instance to start. "); await WaitForInstanceState(ec2InstanceId, InstanceStateName.Running); } catch (AmazonEC2Exception ec2Exception) { if (ec2Exception.ErrorCode == "InvalidInstanceId") { _logger.LogError( $"InstanceId is invalid, unable to start. {ec2Exception.Message}"); } throw; } catch (Exception ex) { _logger.LogError( $"An error occurred while starting the instance.: {ex.Message}"); throw; } } /// <summary> /// Wait until an EC2 instance is in a specified state. /// </summary> /// <param name="instanceId">The instance Id.</param> /// <param name="stateName">The state to wait for.</param> /// <returns>A Boolean value indicating the success of the action.</returns> public async Task<bool> WaitForInstanceState(string instanceId, InstanceStateName stateName) { var request = new DescribeInstancesRequest { InstanceIds = new List<string> { instanceId } }; // Wait until the instance is in the specified state. var hasState = false; do { // Wait 5 seconds. Thread.Sleep(5000); // Check for the desired state. var response = await _amazonEC2.DescribeInstancesAsync(request); var instance = response.Reservations[0].Instances[0]; hasState = instance.State.Name == stateName; Console.Write(". "); } while (!hasState); return hasState; }
  • For API details, see StartInstances in Amazon SDK for .NET API Reference.

Bash
Amazon CLI with Bash script
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

############################################################################### # function ec2_start_instances # # This function starts one or more Amazon Elastic Compute Cloud (Amazon EC2) instances. # # Parameters: # -i instance_id - The ID(s) of the instance(s) to start (comma-separated). # -h - Display help. # # Returns: # 0 - If successful. # 1 - If it fails. ############################################################################### function ec2_start_instances() { local instance_ids local option OPTARG # Required to use getopts command in a function. # bashsupport disable=BP5008 function usage() { echo "function ec2_start_instances" echo "Starts one or more Amazon Elastic Compute Cloud (Amazon EC2) instances." echo " -i instance_id - The ID(s) of the instance(s) to start (comma-separated)." echo " -h - Display help." echo "" } # Retrieve the calling parameters. while getopts "i:h" option; do case "${option}" in i) instance_ids="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$instance_ids" ]]; then errecho "ERROR: You must provide one or more instance IDs with the -i parameter." usage return 1 fi response=$(aws ec2 start-instances \ --instance-ids "${instance_ids}") || { aws_cli_error_log ${?} errecho "ERROR: AWS reports start-instances operation failed with $response." return 1 } return 0 }

The utility functions used in this example.

############################################################################### # function errecho # # This function outputs everything sent to it to STDERR (standard error output). ############################################################################### function errecho() { printf "%s\n" "$*" 1>&2 } ############################################################################## # function aws_cli_error_log() # # This function is used to log the error messages from the AWS CLI. # # The function expects the following argument: # $1 - The error code returned by the AWS CLI. # # Returns: # 0: - Success. # ############################################################################## function aws_cli_error_log() { local err_code=$1 errecho "Error code : $err_code" if [ "$err_code" == 1 ]; then errecho " One or more S3 transfers failed." elif [ "$err_code" == 2 ]; then errecho " Command line failed to parse." elif [ "$err_code" == 130 ]; then errecho " Process received SIGINT." elif [ "$err_code" == 252 ]; then errecho " Command syntax invalid." elif [ "$err_code" == 253 ]; then errecho " The system environment or configuration was invalid." elif [ "$err_code" == 254 ]; then errecho " The service returned an error." elif [ "$err_code" == 255 ]; then errecho " 255 is a catch-all error." fi return 0 }
  • For API details, see StartInstances in Amazon CLI Command Reference.

C++
SDK for C++
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

//! Start an Amazon Elastic Compute Cloud (Amazon EC2) instance. /*! \param instanceID: An EC2 instance ID. \param clientConfiguration: AWS client configuration. \return bool: Function succeeded. */ bool AwsDoc::EC2::startInstance(const Aws::String &instanceId, const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::EC2::EC2Client ec2Client(clientConfiguration); Aws::EC2::Model::StartInstancesRequest startRequest; startRequest.AddInstanceIds(instanceId); startRequest.SetDryRun(true); Aws::EC2::Model::StartInstancesOutcome dryRunOutcome = ec2Client.StartInstances(startRequest); if (dryRunOutcome.IsSuccess()) { std::cerr << "Failed dry run to start instance. A dry run should trigger an error." << std::endl; return false; } else if (dryRunOutcome.GetError().GetErrorType() != Aws::EC2::EC2Errors::DRY_RUN_OPERATION) { std::cout << "Failed dry run to start instance " << instanceId << ": " << dryRunOutcome.GetError().GetMessage() << std::endl; return false; } startRequest.SetDryRun(false); Aws::EC2::Model::StartInstancesOutcome startInstancesOutcome = ec2Client.StartInstances(startRequest); if (!startInstancesOutcome.IsSuccess()) { std::cout << "Failed to start instance " << instanceId << ": " << startInstancesOutcome.GetError().GetMessage() << std::endl; } else { std::cout << "Successfully started instance " << instanceId << std::endl; } return startInstancesOutcome.IsSuccess(); }
  • For API details, see StartInstances in Amazon SDK for C++ API Reference.

CLI
Amazon CLI

To start an Amazon EC2 instance

This example starts the specified Amazon EBS-backed instance.

Command:

aws ec2 start-instances --instance-ids i-1234567890abcdef0

Output:

{ "StartingInstances": [ { "InstanceId": "i-1234567890abcdef0", "CurrentState": { "Code": 0, "Name": "pending" }, "PreviousState": { "Code": 80, "Name": "stopped" } } ] }

For more information, see Stop and Start Your Instance in the Amazon Elastic Compute Cloud User Guide.

  • For API details, see StartInstances in Amazon CLI Command Reference.

Java
SDK for Java 2.x
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

/** * Starts an Amazon EC2 instance asynchronously and waits until it is in the "running" state. * * @param instanceId the ID of the instance to start * @return a {@link CompletableFuture} that completes when the instance has been started and is in the "running" state, or exceptionally if an error occurs */ public CompletableFuture<Void> startInstanceAsync(String instanceId) { StartInstancesRequest startRequest = StartInstancesRequest.builder() .instanceIds(instanceId) .build(); Ec2AsyncWaiter ec2Waiter = Ec2AsyncWaiter.builder() .client(getAsyncClient()) .build(); DescribeInstancesRequest describeRequest = DescribeInstancesRequest.builder() .instanceIds(instanceId) .build(); logger.info("Starting instance " + instanceId + " and waiting for it to run."); CompletableFuture<Void> resultFuture = new CompletableFuture<>(); return getAsyncClient().startInstances(startRequest) .thenCompose(response -> ec2Waiter.waitUntilInstanceRunning(describeRequest) ) .thenAccept(waiterResponse -> { logger.info("Successfully started instance " + instanceId); resultFuture.complete(null); }) .exceptionally(throwable -> { resultFuture.completeExceptionally(new RuntimeException("Failed to start instance: " + throwable.getMessage(), throwable)); return null; }); }
  • For API details, see StartInstances in Amazon SDK for Java 2.x API Reference.

JavaScript
SDK for JavaScript (v3)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

import { EC2Client, StartInstancesCommand } from "@aws-sdk/client-ec2"; import { fileURLToPath } from "node:url"; import { parseArgs } from "node:util"; /** * Starts an Amazon EBS-backed instance that you've previously stopped. * @param {{ instanceIds }} options */ export const main = async ({ instanceIds }) => { const client = new EC2Client({}); const command = new StartInstancesCommand({ InstanceIds: instanceIds, }); try { const { StartingInstances } = await client.send(command); const instanceIdList = StartingInstances.map( (instance) => ` • ${instance.InstanceId}`, ); console.log("Starting instances:"); console.log(instanceIdList.join("\n")); } catch (caught) { if ( caught instanceof Error && caught.name === "InvalidInstanceID.NotFound" ) { console.warn(`${caught.message}`); } else { throw caught; } } };
  • For API details, see StartInstances in Amazon SDK for JavaScript API Reference.

Kotlin
SDK for Kotlin
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

suspend fun startInstanceSc(instanceId: String) { val request = StartInstancesRequest { instanceIds = listOf(instanceId) } Ec2Client { region = "us-west-2" }.use { ec2 -> ec2.startInstances(request) println("Waiting until instance $instanceId starts. This will take a few minutes.") ec2.waitUntilInstanceRunning { // suspend call instanceIds = listOf(instanceId) } println("Successfully started instance $instanceId") } }
  • For API details, see StartInstances in Amazon SDK for Kotlin API reference.

PowerShell
Tools for PowerShell

Example 1: This example starts the specified instance.

Start-EC2Instance -InstanceId i-12345678

Output:

CurrentState InstanceId PreviousState ------------ ---------- ------------- Amazon.EC2.Model.InstanceState i-12345678 Amazon.EC2.Model.InstanceState

Example 2: This example starts the specified instances.

@("i-12345678", "i-76543210") | Start-EC2Instance

Example 3: This example starts the set of instances that are currently stopped. The Instance objects returned by Get-EC2Instance are piped to Start-EC2Instance. The syntax used by this example requires PowerShell version 3 or higher.

(Get-EC2Instance -Filter @{ Name="instance-state-name"; Values="stopped"}).Instances | Start-EC2Instance

Example 4: With PowerShell version 2, you must use New-Object to create the filter for the Filter parameter.

$filter = New-Object Amazon.EC2.Model.Filter $filter.Name = "instance-state-name" $filter.Values = "stopped" (Get-EC2Instance -Filter $filter).Instances | Start-EC2Instance
  • For API details, see StartInstances in Amazon Tools for PowerShell Cmdlet Reference.

Python
SDK for Python (Boto3)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

class EC2InstanceWrapper: """Encapsulates Amazon Elastic Compute Cloud (Amazon EC2) instance actions using the client interface.""" def __init__( self, ec2_client: Any, instances: Optional[List[Dict[str, Any]]] = None ) -> None: """ Initializes the EC2InstanceWrapper with an EC2 client and optional instances. :param ec2_client: A Boto3 Amazon EC2 client. This client provides low-level access to AWS EC2 services. :param instances: A list of dictionaries representing Boto3 Instance objects. These are high-level objects that wrap instance actions. """ self.ec2_client = ec2_client self.instances = instances or [] @classmethod def from_client(cls) -> "EC2InstanceWrapper": """ Creates an EC2InstanceWrapper instance with a default EC2 client. :return: An instance of EC2InstanceWrapper initialized with the default EC2 client. """ ec2_client = boto3.client("ec2") return cls(ec2_client) def start(self) -> Optional[Dict[str, Any]]: """ Starts instances and waits for them to be in a running state. :return: The response to the start request. """ if not self.instances: logger.info("No instances to start.") return None instance_ids = [instance["InstanceId"] for instance in self.instances] try: start_response = self.ec2_client.start_instances(InstanceIds=instance_ids) waiter = self.ec2_client.get_waiter("instance_running") waiter.wait(InstanceIds=instance_ids) return start_response except ClientError as err: logger.error( f"Failed to start instance(s): {','.join(map(str, instance_ids))}" ) error_code = err.response["Error"]["Code"] if error_code == "IncorrectInstanceState": logger.error( "Couldn't start instance(s) because they are in an incorrect state. " "Ensure the instances are in a stopped state before starting them." ) raise
  • For API details, see StartInstances in Amazon SDK for Python (Boto3) API Reference.

Ruby
SDK for Ruby
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

require 'aws-sdk-ec2' # Attempts to start an Amazon Elastic Compute Cloud (Amazon EC2) instance. # # Prerequisites: # # - The Amazon EC2 instance. # # @param ec2_client [Aws::EC2::Client] An initialized EC2 client. # @param instance_id [String] The ID of the instance. # @return [Boolean] true if the instance was started; otherwise, false. # @example # exit 1 unless instance_started?( # Aws::EC2::Client.new(region: 'us-west-2'), # 'i-123abc' # ) def instance_started?(ec2_client, instance_id) response = ec2_client.describe_instance_status(instance_ids: [instance_id]) if response.instance_statuses.count.positive? state = response.instance_statuses[0].instance_state.name case state when 'pending' puts 'Error starting instance: the instance is pending. Try again later.' return false when 'running' puts 'The instance is already running.' return true when 'terminated' puts 'Error starting instance: ' \ 'the instance is terminated, so you cannot start it.' return false end end ec2_client.start_instances(instance_ids: [instance_id]) ec2_client.wait_until(:instance_running, instance_ids: [instance_id]) puts 'Instance started.' true rescue StandardError => e puts "Error starting instance: #{e.message}" false end # Example usage: def run_me instance_id = '' region = '' # Print usage information and then stop. if ARGV[0] == '--help' || ARGV[0] == '-h' puts 'Usage: ruby ec2-ruby-example-start-instance-i-123abc.rb ' \ 'INSTANCE_ID REGION ' # Replace us-west-2 with the AWS Region you're using for Amazon EC2. puts 'Example: ruby ec2-ruby-example-start-instance-i-123abc.rb ' \ 'i-123abc us-west-2' exit 1 # If no values are specified at the command prompt, use these default values. # Replace us-west-2 with the AWS Region you're using for Amazon EC2. elsif ARGV.count.zero? instance_id = 'i-123abc' region = 'us-west-2' # Otherwise, use the values as specified at the command prompt. else instance_id = ARGV[0] region = ARGV[1] end ec2_client = Aws::EC2::Client.new(region: region) puts "Attempting to start instance '#{instance_id}' " \ '(this might take a few minutes)...' return if instance_started?(ec2_client, instance_id) puts 'Could not start instance.' end run_me if $PROGRAM_NAME == __FILE__
  • For API details, see StartInstances in Amazon SDK for Ruby API Reference.

Rust
SDK for Rust
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

Start an EC2 Instance by instance ID.

pub async fn start_instance(&self, instance_id: &str) -> Result<(), EC2Error> { tracing::info!("Starting instance {instance_id}"); self.client .start_instances() .instance_ids(instance_id) .send() .await?; tracing::info!("Started instance."); Ok(()) }

Wait for an instance to be in the ready and status ok states, using the Waiters API. Using the Waiters API requires `use aws_sdk_ec2::client::Waiters` in the rust file.

/// Wait for an instance to be ready and status ok (default wait 60 seconds) pub async fn wait_for_instance_ready( &self, instance_id: &str, duration: Option<Duration>, ) -> Result<(), EC2Error> { self.client .wait_until_instance_status_ok() .instance_ids(instance_id) .wait(duration.unwrap_or(Duration::from_secs(60))) .await .map_err(|err| match err { WaiterError::ExceededMaxWait(exceeded) => EC2Error(format!( "Exceeded max time ({}s) waiting for instance to start.", exceeded.max_wait().as_secs() )), _ => EC2Error::from(err), })?; Ok(()) }
  • For API details, see StartInstances in Amazon SDK for Rust API reference.

SAP ABAP
SDK for SAP ABAP
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

DATA lt_instance_ids TYPE /aws1/cl_ec2instidstringlist_w=>tt_instanceidstringlist. APPEND NEW /aws1/cl_ec2instidstringlist_w( iv_value = iv_instance_id ) TO lt_instance_ids. "Perform dry run" TRY. " DryRun is set to true. This checks for the required permissions to start the instance without actually making the request. " lo_ec2->startinstances( it_instanceids = lt_instance_ids iv_dryrun = abap_true ). CATCH /aws1/cx_rt_service_generic INTO DATA(lo_exception). " If the error code returned is `DryRunOperation`, then you have the required permissions to start this instance. " IF lo_exception->av_err_code = 'DryRunOperation'. MESSAGE 'Dry run to start instance completed.' TYPE 'I'. " DryRun is set to false to start instance. " oo_result = lo_ec2->startinstances( " oo_result is returned for testing purposes. " it_instanceids = lt_instance_ids iv_dryrun = abap_false ). MESSAGE 'Successfully started the EC2 instance.' TYPE 'I'. " If the error code returned is `UnauthorizedOperation`, then you don't have the required permissions to start this instance. " ELSEIF lo_exception->av_err_code = 'UnauthorizedOperation'. MESSAGE 'Dry run to start instance failed. User does not have permissions to start the instance.' TYPE 'E'. ELSE. DATA(lv_error) = |"{ lo_exception->av_err_code }" - { lo_exception->av_err_msg }|. MESSAGE lv_error TYPE 'E'. ENDIF. ENDTRY.
  • For API details, see StartInstances in Amazon SDK for SAP ABAP API reference.

For a complete list of Amazon SDK developer guides and code examples, see Create Amazon EC2 resources using an Amazon SDK. This topic also includes information about getting started and details about previous SDK versions.