﻿---
title: Getting started
description: This page guides you through the installation process of the Python client, shows you how to instantiate the client, and how to perform basic Elasticsearch...
url: https://www.elastic.co/elastic/docs-builder/docs/2743/reference/elasticsearch/clients/python/getting-started
products:
  - Elasticsearch
  - Elasticsearch Client
  - Elasticsearch Python Client
---

# Getting started
This page guides you through the installation process of the Python client, shows you how to instantiate the client, and how to perform basic Elasticsearch operations with it.

### Requirements

- [Python](https://www.python.org/) 3.10 or newer
- [`pip`](https://pip.pypa.io/en/stable/), installed by default alongside Python


### Installation

To install the latest version of the client, run the following command:
<tab-set>
  <tab-item title="Standard Python">
    ```shell
    python -m pip install elasticsearch
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```shell
    python -m pip install "elasticsearch[async]"
    ```
  </tab-item>
</tab-set>

Refer to the [*Installation*](https://www.elastic.co/elastic/docs-builder/docs/2743/reference/elasticsearch/clients/python/installation) page to learn more.

### Connecting

You can connect to the Elastic Cloud using an API key and the Elasticsearch endpoint.
<tab-set>
  <tab-item title="Standard Python">
    ```py
    import os
    from elasticsearch import Elasticsearch

    client = Elasticsearch(
        "https://...", 
        api_key=os.environ["ELASTIC_API_KEY"],
    )
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```py
    import os
    from elasticsearch import AsyncElasticsearch

    client = AsyncElasticsearch(
        "https://...", 
        api_key=os.environ["ELASTIC_API_KEY"],
    )
    ```
  </tab-item>
</tab-set>

Your Elasticsearch endpoint can be found on the **My deployment** page of your deployment:
![Finding Elasticsearch endpoint](https://www.elastic.co/elastic/docs-builder/docs/2743/reference/elasticsearch/clients/python/images/es-endpoint.jpg)
You can generate an API key on the **Management** page under Security.
![Create API key](https://www.elastic.co/elastic/docs-builder/docs/2743/reference/elasticsearch/clients/python/images/create-api-key.png)
For other connection options, refer to the [*Connecting*](https://www.elastic.co/elastic/docs-builder/docs/2743/reference/elasticsearch/clients/python/connecting) section.

### Operations

Time to use Elasticsearch! This section walks you through the basic, and most important, operations of Elasticsearch. For more operations and more advanced examples, refer to the [*Examples*](https://www.elastic.co/elastic/docs-builder/docs/2743/reference/elasticsearch/clients/python/examples) page.

#### Creating an index

This is how you create the `my_index` index:
<tab-set>
  <tab-item title="Standard Python">
    ```py
    client.indices.create(index="my_index")
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```py
    await client.indices.create(index="my_index")
    ```
  </tab-item>
</tab-set>

Optionally, you can first define the expected types of your features with a custom mapping.
<tab-set>
  <tab-item title="Standard Python">
    ```py
    mappings = {
        "properties": {
            "foo": {"type": "text"},
            "bar": {
                "type": "text",
                "fields": {
                    "keyword": {
                        "type": "keyword",
                        "ignore_above": 256,
                    }
                },
            },
        }
    }

    client.indices.create(index="my_index", mappings=mappings)
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```py
    mappings = {
        "properties": {
            "foo": {"type": "text"},
            "bar": {
                "type": "text",
                "fields": {
                    "keyword": {
                        "type": "keyword",
                        "ignore_above": 256,
                    }
                },
            },
        }
    }

    await client.indices.create(index="my_index", mappings=mappings)
    ```
  </tab-item>
</tab-set>


#### Indexing documents

This indexes a document with the index API:
<tab-set>
  <tab-item title="Standard Python">
    ```py
    client.index(
        index="my_index",
        id="my_document_id",
        document={
            "foo": "foo",
            "bar": "bar",
        }
    )
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```py
    await client.index(
        index="my_index",
        id="my_document_id",
        document={
            "foo": "foo",
            "bar": "bar",
        }
    )
    ```
  </tab-item>
</tab-set>

You can also index multiple documents at once with the bulk helper function:
<tab-set>
  <tab-item title="Standard Python">
    ```py
    from elasticsearch import helpers

    def generate_docs():
        for i in range(10):
            yield {
                "_index": "my_index",
                "foo": f"foo {i}",
                "bar": "bar",
            }

    helpers.bulk(client, generate_docs())
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```py
    from elasticsearch import helpers

    async def generate_docs():
        for i in range(10):
            yield {
                "_index": "my_index",
                "foo": f"foo {i}",
                "bar": "bar",
            }

    async def bulk_example():
        await helpers.async_bulk(client, generate_docs())
    ```
  </tab-item>
</tab-set>

These helpers are the recommended way to perform bulk ingestion. While it is also possible to perform bulk ingestion using `client.bulk` directly, the helpers handle retries, ingesting chunk by chunk and more. See the [*Client helpers*](https://www.elastic.co/elastic/docs-builder/docs/2743/reference/elasticsearch/clients/python/client-helpers) page for more details.

#### Getting documents

You can get documents by using the following code:
<tab-set>
  <tab-item title="Standard Python">
    ```py
    client.get(index="my_index", id="my_document_id")
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```py
    await client.get(index="my_index", id="my_document_id")
    ```
  </tab-item>
</tab-set>


#### Searching documents

This is how you can create a single match query with the Python client:
<tab-set>
  <tab-item title="Standard Python">
    ```py
    client.search(index="my_index", query={
        "match": {
            "foo": "foo"
        }
    })
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```py
    await client.search(index="my_index", query={
        "match": {
            "foo": "foo"
        }
    })
    ```
  </tab-item>
</tab-set>


#### Updating documents

This is how you can update a document, for example to add a new field:
<tab-set>
  <tab-item title="Standard Python">
    ```py
    client.update(
        index="my_index",
        id="my_document_id",
        doc={
            "foo": "bar",
            "new_field": "new value",
        }
    )
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```py
    await client.update(
        index="my_index",
        id="my_document_id",
        doc={
            "foo": "bar",
            "new_field": "new value",
        }
    )
    ```
  </tab-item>
</tab-set>


#### Deleting documents

<tab-set>
  <tab-item title="Standard Python">
    ```py
    client.delete(index="my_index", id="my_document_id")
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```py
    await client.delete(index="my_index", id="my_document_id")
    ```
  </tab-item>
</tab-set>


#### Deleting an index

<tab-set>
  <tab-item title="Standard Python">
    ```py
    client.indices.delete(index="my_index")
    ```
  </tab-item>

  <tab-item title="Async Python">
    ```py
    await client.indices.delete(index="my_index")
    ```
  </tab-item>
</tab-set>


## Further reading

- Use [*Client helpers*](https://www.elastic.co/elastic/docs-builder/docs/2743/reference/elasticsearch/clients/python/client-helpers) for a more comfortable experience with the APIs.