Getting Started

Installation

The linode-api package can be installed from pypi as shown below:

pip install linode-api

If you prefer, you can clone the package from github and install it from source:

git clone git@github.com:Linode/python-linode-api
cd python-linode-api
python setup.py install

Note

This library uses the “linode” namespace. This could conflict with other libraries intended to interact with older versions of the Linode API. If you depend on a python library to interact with older versions of the Linode API, consider using a virtualenv when installing this library.

Authentication

In order to make requests to the Linode API, you will need a token. To generate one, log in to cloud.linode.com, and on your profile click “Create a Personal Access Token”.

Note

You can also use an OAuth Token to authenticate to the API - see OAuth for details.

When creating a Personal Access Token, you will be prompted for what scopes the token should be created with. These scopes control what parts of your account this token may be used to access - for more information, see OAuth Scopes. Restricting what a token can access is more secure than creating one with access to your entire account, but can be less convenient since you would need to create a new token to access other parts of the account. For the examples on this page, your Personal Access Token must be able to view and create Linodes.

Listing your Linodes

Using the token you generated above, create a LinodeClient object that will be used for all interactions with the API.:

from linode import LinodeClient
client = LinodeClient(token)

This object will manage all requests you make through the API. Once it’s set up, you can use it to retrieve and print a list of your Linodes:

my_linodes = client.linode.get_instances()

for current_linode in my_linodes:
    print(current_linode.label)

When retrieving collections of objects from the API, a list-like object is returned, and may be iterated over or indexed as a normal list.

Creating a Linode

In order to create a Linode, we need a few pieces of information:

  • what :py:class:Region to create the Linode in
  • what :py:class:Type of Linode to create
  • what :py:class:Image to deploy to the new Linode.

We can query for these values similarly to how we listed our Linodes above:

available_regions = client.get_regions()

We could also use values that we know in advance to avoid the need to query the API. For example, we may know that we want a g5-standard-4 Linode running the linode/debian9 Image. Both objects and IDs are accepted when creating a Linode.:

chosen_region = available_regions[0]

new_linode, password = client.linode.create_instance(chosen_region,
                                                     'g5-standard-4',
                                                     image='linode/debian9')

create_instance() returns the newly-created Linode object and the root password that was generated for it. This Linode will boot automatically, and should be available shortly. Finally, let’s print out the results so we can access our new server.

print("ssh root@{} - {}".format(new_linode.ipv4[0], password))

Continue on to Core Concepts