Python SDK


This SDK tool is under active development For any bug found or feature request, feel free to open any issue regarding this SDK tool in our in our community repo


  • Python 3.8+
  • Pip | Poetry


Install it directly into an activated virtual environment:


pip install instill-sdk


If your host machine is on arm64 architecture (including Apple silicon machines, equipped with m1/m2 processors), there are some issues when installing grpcio within conda environment. You will have to manually build and install it like below. Read more about this issue here.

GRPC_PYTHON_LDFLAGS=" -framework CoreFoundation" pip install grpcio --no-binary :all:

#Check Import

After installation, you can check if it has been installed correctly:

>>> import instill
>>> instill.__version__

#Config Instill Core or Instill Cloud Instance

Before we can start using this SDK, you will need to properly config your target instance. We support two ways to setup the configs, which are

#Config file

Create a config file under this path ${HOME}/.config/instill/sdk/python/config.yml, and within the file you will need to fill in some basic parameters for your desired host.1

Within the config file, you can define multiple instances with the alias of your liking. Later in the SDK you can refer to this alias to switch between instances.2

url: str
secure: bool
token: str
url: str
secure: bool
token: str


url: localhost:8080
secure: false
token: instill_sk***
secure: true
token: instill_sk***

#At runtime

If you do not like the idea of having to create a config file, you can also setup your target instance by doing the following at the very beginning of your script.

from instill.configuration import global_config


#Create Client

Simply import the get_client function to get the client that are connected to all services with the config you setup previously.

from instill.clients import get_client
client = get_client()


Remember to call client.close() at the end of script to release the channel and the underlying resources.

If you have not set up Instill VDP or Instill Model, you will get a warning like this:

2023-09-27 18:49:04,871.871 WARNING Instill VDP is not serving, VDP functionalities will not work
2023-09-27 18:49:04,907.907 WARNING Instill Model is not serving, Model functionalities will not work

You can check the readiness of each service:

# True
# True
# True


Depends on which project(Instill VDP or Instill Model or both) you had launched locally, some services might not be available.

After making sure all desired services are serving, we can check the user status by:


If you have a valid api_token in your config file, you should see something like this:

name: "users/admin"
uid: "4767b74d-640a-4cdf-9c6d-7bb0e36098a0"
id: "admin"
create_time {
seconds: 1695589596
nanos: 36522000
update_time {
seconds: 1695589749
nanos: 544980000
email: ""
first_name: "Instill"
last_name: "AI"
org_name: "Instill AI"
role: "hobbyist"
newsletter_subscription: true
cookie_token: ""


Python SDK is currently under some refactoring jobs, the rest of this page will be populated soon. Stay-tuned!


  1. You can obtain an api_token, by simply going to Settings > API Tokens page from the console, no matter whether it is Instill Core or Instill Cloud.

  2. SDK will look for alias default first. If it is not found, it will load the config for the first alias in the config file.

Last updated: 6/21/2024, 11:39:07 AM