vastai / vastai_sdk)The vastai package provides a Python SDK for managing GPU instances, volumes, serverless endpoints, and billing on Vast.ai. The vastai_sdk package is a backward-compatibility shim that re-exports vastai.
pip install vastai\nFor serverless and async support:
\npip install \"vastai[serverless]\"\nThe SDK reads the API key from ~/.vast_api_key by default. You can also pass it explicitly:
from vastai import VastAI\nvast = VastAI() # reads ~/.vast_api_key\nvast = VastAI(api_key=\"YOUR_API_KEY\") # explicit key\nGet your API key from https://console.vast.ai/manage-keys/
\nThe old vastai_sdk import still works:
from vastai_sdk import VastAI # equivalent to: from vastai import VastAI\nfrom vastai import VastAI\nvast = VastAI(api_key=None, server_url=None, retry=3, raw=False, quiet=False)\n# List all your instances\ninstances = vast.show_instances()\n\n# Get a single instance\ninstance = vast.show_instance(id=12345)\n\n# Search GPU offers\noffers = vast.search_offers(query='gpu_name=RTX_4090 num_gpus>=4 reliability>0.99')\n\n# Create an instance from an offer\nresult = vast.create_instance(id=<offer_id>, image=\"pytorch/pytorch:latest\", disk=50)\n\n# ...as a jupyter instance on a direct connection\nresult = vast.create_instance(id=<offer_id>, image=\"pytorch/pytorch:latest\", disk=50,\n jupyter=True, direct=True, jupyter_lab=True)\n\n# Lifecycle\nvast.start_instance(id=12345)\nvast.stop_instance(id=12345)\nvast.reboot_instance(id=12345)\nvast.destroy_instance(id=12345)\n\n# Label an instance\nvast.label_instance(id=12345, label=\"my-training-run\")\n\n# Get SSH connection string\nssh_url = vast.ssh_url(id=12345) # returns \"ssh -p PORT user@host\"\nscp_url = vast.scp_url(id=12345) # returns scp-compatible URL\nInterruptible (spot) instances are priced below on-demand instances, but can be interrupted at any time by another user with a lower bid. Note: vast.search_offers(type='bid', ...) exposes min_bid, but vast.create_instance(...) defaults to on-demand at dph_total unless you pass bid_price=<floor>. Always pass bid_price after a type='bid' search, otherwise the instance will be rented as an on-demand instance/price instead of as an interruptible.
When outbid, the instance moves to stopped (not destroyed) and storage charges continue. Resume by raising the bid via vast.change_bid(id=..., price=...).
# Search GPU offers (use help(vast.search_offers) for full query syntax)\noffers = vast.search_offers(query='gpu_name=RTX_3090 num_gpus>=2')\n\n# Search volume offers\nvolumes = vast.search_volumes(query='...')\n\n# Search network volumes\nnet_vols = vast.search_network_volumes()\n\n# Search templates\ntemplates = vast.search_templates()\n\n# Search invoices\ninvoices = vast.search_invoices()\n# copy() takes vast URLs: \"[C.|V.]id:path\", \"cloud_service[.id]:path\", or \"local:path\"\nvast.copy(\"local:./data/\", \"C.12345:/workspace/data/\") # Local → instance\nvast.copy(\"C.12345:/workspace/results/\", \"local:./out/\") # Instance → local\nvast.copy(\"12345:/workspace/\", \"67890:/workspace/\") # Instance → instance (legacy format)\nvast.copy(\"s3.101:/data/\", \"C.12345:/workspace/\") # Cloud service → instance\nvast.copy(\"V.1234:/file\", \"C.5678:/workspace/\") # Volume → instance\nvast.copy(\"V.1234:/file\", \"s3.101:/workspace/\") # Volume → cloud service\n\nvast.cancel_copy(dst_id=12345) # Cancel an in-progress copy\n\n# Cloud sync via a saved cloud connection (see the UI settings page for connection IDs)\nvast.cloud_copy(src=\"./data\", dst=\"s3://bucket/path\", instance=12345,\n connection=<conn_id>, transfer=\"Instance To Cloud\")\nvast.cancel_sync(dst_id=12345)\nVolume copy is currently only supported for copying to other volumes, instances, or cloud services, not local. Do not use /root or / as a destination directory — it breaks ssh permissions on the instance and future copies fail. See https://vast.ai/docs/gpu-instances/data-movement#constraints.
# List all deployments\ndeployments = vast.show_deployments()\n\n# Get a deployment\ndeployment = vast.show_deployment(id=42)\n\n# Delete a deployment\nvast.delete_deployment(id=42)\nmachines = vast.show_machines()\nmachine = vast.show_machine(id=10)\nvast.list_machine(id=10, price_gpu=0.30)\nvast.unlist_machine(id=10)\nkeys = vast.show_ssh_keys()\nvast.create_ssh_key(ssh_key=\"ssh-rsa AAAA...\")\nvast.delete_ssh_key(id=5)\nmembers = vast.show_members()\nvast.invite_member(email=\"user@example.com\", role=\"developer\")\nvast.remove_member(id=7)\nSyncClient provides typed, synchronous access to GPU offers and instances.
from vastai import SyncClient\n\nclient = SyncClient(api_key=\"YOUR_API_KEY\") # or reads ~/.vast_api_key\n\n# Search offers with structured filters\noffers = client.search(\n num_gpus=2,\n gpu_name=\"RTX_4090\",\n min_reliability=0.99,\n max_dph_total=2.0,\n)\n\n# Create an instance (SyncClient takes an InstanceConfig, not loose kwargs)\nfrom vastai.data.instance import InstanceConfig\n\ninstance = client.create_instance(\n offer_id=<id>,\n config=InstanceConfig(image=\"pytorch/pytorch:latest\", disk=50),\n)\n\n# List your instances\ninstances = client.show_instances() # returns list[SyncInstance]\n\n# Destroy an instance\nclient.destroy_instance(instance_or_id=12345)\nAsyncClient provides async access to GPU offers and instances. Use as an async context manager.
import asyncio\nfrom vastai import AsyncClient\nfrom vastai.data.instance import InstanceConfig\n\nasync def main():\n async with AsyncClient(api_key=\"YOUR_API_KEY\") as client:\n # Search offers\n offers = await client.search(num_gpus=1, gpu_name=\"A100\")\n\n # Create instance\n instance = await client.create_instance(\n offer_id=<id>, config=InstanceConfig(image=\"ubuntu:22.04\"))\n\n # List instances\n instances = await client.show_instances() # returns list[AsyncInstance]\n\n # Destroy instance\n await client.destroy_instance(instance_or_id=instance.id)\n\nasyncio.run(main())\nFor inference endpoints (requires pip install \"vastai[serverless]\"):
import asyncio\nfrom vastai import Serverless\n\nasync def main():\n serverless = Serverless() # reads ~/.vast_api_key\n\n # Get an endpoint\n endpoint = await serverless.get_endpoint(\"my-endpoint\")\n\n # Make a request\n response = await serverless.request(\"/v1/completions\", {\n \"model\": \"Qwen/Qwen3-8B\",\n \"prompt\": \"Who are you?\",\n \"max_tokens\": 100,\n \"temperature\": 0.7,\n })\n\n text = response[\"response\"][\"choices\"][0][\"text\"]\n print(text)\n\nasyncio.run(main())\n# Find cheapest 4x RTX 4090 and launch a job\nfrom vastai import VastAI\nvast = VastAI()\n\noffers = vast.search_offers(query='gpu_name=RTX_4090 num_gpus=4 reliability>0.99')\ncheapest = min(offers, key=lambda o: o['dph_total'])\nresult = vast.create_instance(id=cheapest['id'], image=\"pytorch/pytorch:latest\", disk=100)\nprint(f\"Launched instance: {result['new_contract']}\")\n\n# Use help() to explore method signatures\nhelp(vast.search_offers)\nhelp(vast.create_instance)\n