> ## Documentation Index
> Fetch the complete documentation index at: https://vastai-80aa3a82-examples-openclaw-openai-serverless.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# VastAI.launch_instance

Launch the best matching instance based on GPU/image criteria.

Searches for available offers and creates an instance from the top result.

## Signature

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

## Parameters

<ParamField path="gpu_name" type="str" required>
  Name of the GPU model (replace spaces with underscores, e.g. "RTX\_4090").
</ParamField>

<ParamField path="num_gpus" type="str" required>
  Number of GPUs required (choices: 1, 2, 4, 8, 12, 14).
</ParamField>

<ParamField path="image" type="str" required>
  Docker image name to use for the instance.
</ParamField>

<ParamField path="region" type="str">
  Geographical region filter for the instance location.
</ParamField>

<ParamField path="disk" type="float" default="16.0">
  Disk space to allocate in GB.
</ParamField>

<ParamField path="limit" type="int" default="3">
  Maximum number of offers to consider when selecting the best match.
</ParamField>

<ParamField path="order" type="str" default="&#x22;score-&#x22;">
  Sort order for offers; append '-' to sort descending (e.g. "score-").
</ParamField>

<ParamField path="login" type="str">
  Docker login credentials for private registry authentication.
</ParamField>

<ParamField path="label" type="str">
  Label to attach to the instance.
</ParamField>

<ParamField path="onstart" type="str">
  Filename of an onstart script to run on instance start.
</ParamField>

<ParamField path="onstart_cmd" type="str">
  Shell command to run on instance start.
</ParamField>

<ParamField path="entrypoint" type="str">
  Override the Docker image entrypoint.
</ParamField>

<ParamField path="ssh" type="bool" default="False">
  Enable SSH access to the instance.
</ParamField>

<ParamField path="jupyter" type="bool" default="False">
  Enable Jupyter notebook server.
</ParamField>

<ParamField path="direct" type="bool" default="False">
  Enable direct (peer-to-peer) connections.
</ParamField>

<ParamField path="jupyter_dir" type="str">
  Directory to serve Jupyter from.
</ParamField>

<ParamField path="jupyter_lab" type="bool" default="False">
  Enable JupyterLab instead of classic Jupyter.
</ParamField>

<ParamField path="lang_utf8" type="bool" default="False">
  Set system language encoding to UTF-8.
</ParamField>

<ParamField path="python_utf8" type="bool" default="False">
  Set Python I/O encoding to UTF-8.
</ParamField>

<ParamField path="extra" type="str">
  Extra Docker run arguments passed verbatim.
</ParamField>

<ParamField path="env" type="str">
  Environment variables to set (formatted as Docker -e flags).
</ParamField>

<ParamField path="args" type="list">
  Additional positional arguments.
</ParamField>

<ParamField path="force" type="bool" default="False">
  Skip sanity checks when creating from an existing instance.
</ParamField>

<ParamField path="cancel_unavail" type="bool" default="False">
  Return an error if scheduling fails rather than creating a stopped instance.
</ParamField>

<ParamField path="template_hash" type="str">
  Hash of an instance template to use for configuration.
</ParamField>

<ParamField path="explain" type="bool" default="False">
  Print verbose explanations of API calls made.
</ParamField>

<ParamField path="raw" type="bool" default="False">
  Return raw JSON responses.
</ParamField>

## Returns

`str`, Result from the API call.

## Example

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

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