> ## Documentation Index
> Fetch the complete documentation index at: https://vastai-80aa3a82-auto-cli-sdk-preview-pr-398.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# VastAI.launch_instance

Launch the top instance from search offers matching the given criteria.

## Signature

```python theme={null}
VastAI.launch_instance(
    gpu_name: str,
    num_gpus: str,
    image: str,
    region: Optional[str] = None,
    disk: Optional[float] = 16.0,
    limit: Optional[int] = 3,
    order: Optional[str] = 'score-',
    login: Optional[str] = None,
    label: Optional[str] = None,
    onstart: Optional[str] = None,
    onstart_cmd: Optional[str] = None,
    entrypoint: Optional[str] = None,
    ssh: bool = False,
    jupyter: bool = False,
    direct: bool = False,
    jupyter_dir: Optional[str] = None,
    jupyter_lab: bool = False,
    lang_utf8: bool = False,
    python_utf8: bool = False,
    env: Optional[str] = None,
    args: Optional[str] = None,
    cancel_unavail: bool = False,
    template_hash: Optional[str] = None
) -> dict
```

## Parameters

<ParamField path="gpu_name" type="str" required>
  Name of the GPU model, replace spaces with underscores
</ParamField>

<ParamField path="num_gpus" type="str" required>
  Number of GPUs required
</ParamField>

<ParamField path="image" type="str" required>
  Name of the image to use for instance
</ParamField>

<ParamField path="region" type="Optional[str]">
  Geographical location of the instance
</ParamField>

<ParamField path="disk" type="Optional[float]" default="16.0">
  Disk space required in GB
</ParamField>

<ParamField path="limit" type="Optional[int]" default="3" />

<ParamField path="order" type="Optional[str]" default="score-">
  Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'num\_gpus,total\_flops-'.  default='score-'
</ParamField>

<ParamField path="login" type="Optional[str]">
  docker login arguments for private repo authentication, surround with ''
</ParamField>

<ParamField path="label" type="Optional[str]">
  label to set on the instance
</ParamField>

<ParamField path="onstart" type="Optional[str]">
  filename to use as onstart script
</ParamField>

<ParamField path="onstart_cmd" type="Optional[str]">
  contents of onstart script as single argument
</ParamField>

<ParamField path="entrypoint" type="Optional[str]">
  override entrypoint for args launch instance
</ParamField>

<ParamField path="ssh" type="bool">
  Launch as an ssh instance type
</ParamField>

<ParamField path="jupyter" type="bool">
  Launch as a jupyter instance instead of an ssh instance
</ParamField>

<ParamField path="direct" type="bool">
  Use (faster) direct connections for jupyter & ssh
</ParamField>

<ParamField path="jupyter_dir" type="Optional[str]">
  For runtype 'jupyter', directory in instance to use to launch jupyter. Defaults to image's working directory
</ParamField>

<ParamField path="jupyter_lab" type="bool">
  For runtype 'jupyter', Launch instance with jupyter lab
</ParamField>

<ParamField path="lang_utf8" type="bool">
  Workaround for images with locale problems: install and generate locales before instance launch, and set locale to C.UTF-8
</ParamField>

<ParamField path="python_utf8" type="bool">
  Workaround for images with locale problems: set python's locale to C.UTF-8
</ParamField>

<ParamField path="env" type="Optional[str]">
  env variables and port mapping options, surround with ''
</ParamField>

<ParamField path="args" type="Optional[str]">
  list of arguments passed to container ENTRYPOINT. Onstart is recommended for this purpose. (must be last argument)
</ParamField>

<ParamField path="cancel_unavail" type="bool">
  Return error if scheduling fails (rather than creating a stopped instance)
</ParamField>

<ParamField path="template_hash" type="Optional[str]">
  template hash which contains all relevant information about an instance. This can be used as a replacement for other parameters describing the instance configuration
</ParamField>

## Returns

`dict`

## Example

```python theme={null}
from vastai import VastAI

client = VastAI(api_key="YOUR_API_KEY")
result = client.launch_instance(gpu_name="value", num_gpus="value", image="value")
print(result)
```