---
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/3016/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 later
- [`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:
```shell
python -m pip install elasticsearch
```
```shell
python -m pip install "elasticsearch[async]"
```
Refer to the [*Installation*](https://www.elastic.co/elastic/docs-builder/docs/3016/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.
```py
import os
from elasticsearch import Elasticsearch
client = Elasticsearch(
"https://...",
api_key=os.environ["ELASTIC_API_KEY"],
)
```
```py
import os
from elasticsearch import AsyncElasticsearch
client = AsyncElasticsearch(
"https://...",
api_key=os.environ["ELASTIC_API_KEY"],
)
```
Your Elasticsearch endpoint can be found on the **My deployment** page of your deployment:
You can generate an API key on the **Management** page under Security.
For other connection options, refer to the [*Connecting*](https://www.elastic.co/elastic/docs-builder/docs/3016/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/3016/reference/elasticsearch/clients/python/examples) page.
#### Creating an index
This is how you create the `my_index` index:
```py
client.indices.create(index="my_index")
```
```py
await client.indices.create(index="my_index")
```
Optionally, you can first define the expected types of your features with a custom mapping.
```py
mappings = {
"properties": {
"foo": {"type": "text"},
"bar": {
"type": "text",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256,
}
},
},
}
}
client.indices.create(index="my_index", mappings=mappings)
```
```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)
```
#### Indexing documents
This indexes a document with the index API:
```py
client.index(
index="my_index",
id="my_document_id",
document={
"foo": "foo",
"bar": "bar",
}
)
```
```py
await client.index(
index="my_index",
id="my_document_id",
document={
"foo": "foo",
"bar": "bar",
}
)
```
You can also index multiple documents at once with the bulk helper function:
```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())
```
```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())
```
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. Refer to the [*Client helpers*](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/clients/python/client-helpers) page for more details.
#### Getting documents
You can get documents by using the following code:
```py
client.get(index="my_index", id="my_document_id")
```
```py
await client.get(index="my_index", id="my_document_id")
```
#### Searching documents
This is how you can create a single match query with the Python client:
```py
client.search(index="my_index", query={
"match": {
"foo": "foo"
}
})
```
```py
await client.search(index="my_index", query={
"match": {
"foo": "foo"
}
})
```
#### Updating documents
This is how you can update a document, for example to add a new field:
```py
client.update(
index="my_index",
id="my_document_id",
doc={
"foo": "bar",
"new_field": "new value",
}
)
```
```py
await client.update(
index="my_index",
id="my_document_id",
doc={
"foo": "bar",
"new_field": "new value",
}
)
```
#### Deleting documents
```py
client.delete(index="my_index", id="my_document_id")
```
```py
await client.delete(index="my_index", id="my_document_id")
```
#### Deleting an index
```py
client.indices.delete(index="my_index")
```
```py
await client.indices.delete(index="my_index")
```
## Further reading
- Use [*Client helpers*](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/clients/python/client-helpers) for a more comfortable experience with the APIs.