NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #1813 most downloaded on PyPI
Pinecone Python SDK
Last release 14 days ago
03 Sep 2026
Release timing varies
gaps range from 8 days to 3 months
Nearly every release is documented
notes for 41 of 43 stable releases
1 version withdrawn
withdrawn after publishing
2 years old
97 releases · first in 2024
Nothing published for this version
Nothing published for this version
[Fix] Add missing python-dateutil dependency by @jhamon in https://github.com/pinecone-io/pinecone-python-client/pull/391
One column per month.
To learn more about working with imports and details about expected data formats, please see these documentation guides:
To learn more about working with imports and details about expected data formats, please see these documentation guides:
This release adds methods for interacting with several new endpoints in Public Preview from the Python SDK. Before you can use these, you will need to follow the above docs to prepare your data and configure any storage integrations.
import os
import random
from pinecone import Pinecone, ServerlessSpec, ImportErrorMode
# 0. Instantiate your client instance
pc = Pinecone(api_key=os.environ['PINECONE_API_KEY'])
# 1. You must have an index whose dimension matches the size of your data
# You may already have such an index, but for this demo we will create one.
index_name = f"import-{random.randint(0, 10000)}"
if not pc.has_index(index_name):
pc.create_index(
name=index_name,
dimension=10,
metric="cosine",
spec=ServerlessSpec(cloud="aws", region="eu-west-1")
)
# 2. Get a reference to the index client
index = pc.Index(name=index_name)
# 3. Start the import operation, passing a uri that describes the path to your
# AWS S3 bucket. Each subfolder within this path will correspond to a namespace
# where imported data will be stored.
root = 's3://dev-bulk-import-datasets-pub/10-records-dim-10/'
op = index.start_import(
uri=root,
error_mode=ImportErrorMode.CONTINUE, # or ABORT
# integration_id='' # Add this if you want to use a storage integration
)
# 4. Check the operation status
index.describe_import(id=op.id)
# 5. Cancel an import operation
index.cancel_import(id=op.id)
# 6. List all recent operations using a generator that handles pagination on your behalf
for i in index.list_imports():
print(f"id: {i.id} status: {i.status}")
# ...or turn the generator into a simple list, fetching all results at once
operations = list(index.list_imports())
print(operations)
This release adds a method for interacting with our Rerank endpoint, now in Public Preview. Rerank is used to order results by relevance to a query.
This release adds a method for interacting with our Rerank endpoint, now in Public Preview. Rerank is used to order results by relevance to a query.
Currently rerank supports the bge-reranker-v2-m3 model. See the rerank guide for more information on using this feature.
from pinecone import Pinecone
pc = Pinecone(api_key="your api key")
query = "Tell me about Apple's products"
results = pc.inference.rerank(
model="bge-reranker-v2-m3",
query=query,
documents=[
"Apple is a popular fruit known for its sweetness and crisp texture.",
"Apple is known for its innovative products like the iPhone.",
"Many people enjoy eating apples as a healthy snack.",
"Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.",
"An apple a day keeps the doctor away, as the saying goes.",
],
top_n=3,
return_documents=True,
)
print(query)
for r in results.data:
print(r.score, r.document.text)
Gives output along these lines
Tell me about Apple's products
0.8401279 Apple is known for its innovative products like the iPhone.
0.23318209 Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.
0.17384852 Apple is a popular fruit known for its sweetness and crisp texture.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
In this release, we have renamed the package from pinecone-client to pinecone. From now on you should install it using the pinecone name.
pinecone-client to pineconeIn this release, we have renamed the package from pinecone-client to pinecone. From now on you should install it using the pinecone name.
There is a plan to continue publishing code under the pinecone-client package as well so that anyone using the old name will still find out about available upgrades via their dependency management tool of choice, but we haven't automated that as part of our release process yet so there will be a slight delay in new work being released under that name.
has_index() helper and improved outputWe've added a small helper function to simplify a common need in notebooks and examples, which is checking if an index exists.
from pinecone import Pinecone, ServerlessSpec
pc = Pinecone(api_key='YOUR_API_KEY')
index_name = "movie-recommendations"
if not pc.has_index(index_name):
pc.create_index(
name=index_name,
dimension=384,
metric="cosine",
spec=ServerlessSpec(cloud="aws", region="us-west-2")
)
index = pc.Index(name=index_name)
# Now upsert vectors, run queries, etc
If you are frequently working in notebooks, you will also benefit from a nicer presentation of control plane responses.
>>> pc.describe_index(name="test-embed2")
{
"name": "test-embed2",
"dimension": 10,
"metric": "cosine",
"host": "test-embed2-dojoi3u.svc.apw5-4e34-81fa.pinecone.io",
"spec": {
"serverless": {
"cloud": "aws",
"region": "us-west-2"
}
},
"status": {
"ready": true,
"state": "Ready"
},
"deletion_protection": "disabled"
}
Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v5.0.1...v5.1.0
Nothing published for this version
Nothing published for this version
[CI] Publish doc updates after each release by @jhamon in https://github.com/pinecone-io/pinecone-python-client/pull/373
Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v5.0.0...v5.0.1
All of these properties were available in v3 and v4 releases of the SDK, with deprecation notices shown to affected users.
This updated release of the Pinecone Python SDK depends on API version 2024-07. This v5 SDK release line should continue to receive fixes as long as the 2024-07 API version is in support.
Try out Pinecone's new Inference API, currently in public preview.
from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")
model = "multilingual-e5-large"
# Embed documents
text = [
"Turkey is a classic meat to eat at American Thanksgiving.",
"Many people enjoy the beautiful mosques in Turkey.",
]
text_embeddings = pc.inference.embed(
model=model,
inputs=text,
parameters={"input_type": "passage", "truncate": "END"},
)
If you were previously using the pinecone-plugin-inference plugin package to gain access to this feature with the v4 SDK, you no longer need to install the plugin as it is being included by default.
Use deletion protection to prevent your most important indexes from accidentally being deleted. This feature is available for both serverless and pod indexes.
To enable this feature for existing indexes, use configure_index
from pinecone import Pinecone
pc = Pinecone(api_key='YOUR_API_KEY')
# Enable deletion protection
pc.configure_index(name='example-index', deletion_protection='enabled')
When deletion protection is enabled, calls to delete_index will fail until you first disable the deletion protection.
# To disable deletion protection
pc.configure_index(name='example-index', deletion_protection='disabled')
If you want to enable this feature at the time of index creation, create_index now accepts an optional keyword argument. The feature is disabled by default.
from pinecone import Pinecone, ServerlessSpec
pc = Pinecone(api_key='YOUR_API_KEY')
pc.create_index(
name='example-index',
dimension=1024,
metric='cosine',
deletion_protection='enabled',
spec=ServerlessSpec(cloud='aws', region='us-west-2')
)
As part of an overall move to stop exposing generated code in the package's public interface, an obscure configuration property (openapi_config) was removed in favor of individual configuration options such as proxy_url, proxy_headers, and ssl_ca_certs. All of these properties were available in v3 and v4 releases of the SDK, with deprecation notices shown to affected users.
Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v4.1.2...v5.0.0
do not override port if defined in host by @haruska in https://github.com/pinecone-io/pinecone-python-client/pull/362
Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v4.1.1...v4.1.2
Allow colon inside source tags by @jhamon in https://github.com/pinecone-io/pinecone-python-client/pull/351
Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v4.1.0...v4.1.1
Support proxy_url and ssl_ca_certs options for gRPC by @daverigby in https://github.com/pinecone-io/pinecone-python-client/pull/341
proxy_url and ssl_ca_certs options for gRPC by @daverigby in https://github.com/pinecone-io/pinecone-python-client/pull/341from_texts and from_documents invocations by @jhamon in https://github.com/pinecone-io/pinecone-python-client/pull/342Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v4.0.0...v4.1.0
This is a breaking change for users of the optional GRPC addon (installed with pinecone-client[grpc]). Detailed performance profiling by @daverigby sh…
In this release, we are upgrading theprotobuf dependency in our optional grpc extras from 3.20.3 to 4.25.3.
This is a breaking change for users of the optional GRPC addon (installed with pinecone-client[grpc]). Detailed performance profiling by @daverigby showed this dependency upgrade unlocked a 3x improvement to vector upsert performance in the Python SDK, bringing it much closer to the performance observed in our grpc-based Java SDK.
As a reminder, to use use the optional grpc extras for improved performance, you need to install pinecone-client[grpc] and make a small modification to how you import and use the client. See the instructions for doing this here.
This small release includes a fix for a minor issue introduced last week in the v3.2.0 release that resulted in a DeprecationWarning being incorrectly…
This small release includes a fix for a minor issue introduced last week in the v3.2.0 release that resulted in a DeprecationWarning being incorrectly shown to users who are not passing in the deprecated openapi_config property. This warning notice can safely be ignored by anyone who isn't prepared to upgrade.
Thanks to riku in Pinecone's Community Forum for reporting this issue.
Allow clients to tag requests with a source_tag by @ssmith-pc in https://github.com/pinecone-io/pinecone-python-client/pull/324
The SDK now optionally allows setting a source tag when constructing a Pinecone client. The source tag allows requests to be associated with the source tag provided.
from pinecone import Pinecone
pc = Pinecone(api_key='your-key', source_tag='foo')
# requests initiated from pc connection are associated with source tag "foo"
or
from pinecone.grpc import PineconeGRPC
pc = PineconeGRPC(api_key='your-key', source_tag='foo')
Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v3.2.0...v3.2.1
pc = Pinecone( api_key="YOUR_API_KEY", openapi_config=config ) # this works but emits a deprecation notice ```
In #321 and #325 we implemented four new optional configuration properties that are relevant for users who need to work with proxies:
proxy_url: The location of your proxy. This could be an http or https url depending on your proxy setup.proxy_headers: This param accepts a dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, this is how you can pass basic auth headers with a digest of your username and password.ssl_ca_certs: By default the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the certifi package. If your proxy is using self-signed certs, use this param to specify the path to the certificate (PEM format) we should use to verify your requests.ssl_verify: SSL verification is enabled by default, but it can be disabled to aid in troubleshooting.from pinecone import Pinecone
import urllib3 import make_headers
pc = Pinecone(
api_key="YOUR_API_KEY",
proxy_url='https://your-proxy.com',
proxy_headers=make_headers(proxy_basic_auth='username:password'),
ssl_ca_certs='path/to/cert-bundle.pem'
)
pc.list_indexes()
In older versions of the client you may have passed in proxy configuration to the client like this:
import pinecone
from pinecone.core.client.configuration import OpenApiConfiguration
config = OpenApiConfiguration()
config.ssl_ca_cert = 'path/to/cert-bundle.pem'
config.proxy_headers = make_headers(proxy_basic_auth='username:password')
config.proxy_url = 'https://your-proxy.com'
pinecone.init(
api_key='your-key',
environment='us-east1-gcp',
openapi_config=config
)
If you've tried to pass this openapi_config param into the Pinecone() constructor in the >=3.0 versions of the client, you've run into cryptic bugs telling you your API key is not set (even though it is). We believe we've fixed those bugs in this release, but we strongly encourage you to adopt the new parameters described above. We've decided to move away from having this OpenApiConfiguration as part of our public interface because the object comes from an OpenAPI code generator and has a very large footprint which makes it a challenge from a documentation and testing perspective.
If you were passing configuration through this object for anything not covered by the above four properties, please reach out to let us know and we'll figure out how to handle those configurations going forward.
from pinecone import Pinecone
from pinecone.core.client.configuration import OpenApiConfiguration
import urllib3 import make_headers
config = OpenApiConfiguration()
config.ssl_ca_cert = 'path/to/cert-bundle.pem'
config.proxy_headers = make_headers(proxy_basic_auth='username:password')
config.proxy_url = 'https://your-proxy.com'
pc = Pinecone(
api_key="YOUR_API_KEY",
openapi_config=config
) # this works but emits a deprecation notice
Testing of this feature was done with the help of mitmproxy. You may find it useful to have a look at the tests while troubleshooting your own configuration.
Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v3.1.0...v3.2.0
We've implemented SDK support for a new data plane endpoint used to list ids by prefix in a given namespace. If the prefix empty string is passed, thi
We've implemented SDK support for a new data plane endpoint used to list ids by prefix in a given namespace. If the prefix empty string is passed, this can be used to list all ids in a namespace.
The index client now has list and list_paginated. With clever assignment of vector ids, this can be used to help model hierarchical relationships between different vectors such as when you have embeddings for multiple chunks or fragments related to the same document.
The list method returns a generator that handles pagination on your behalf.
from pinecone import Pinecone
pc = Pinecone(api_key='xxx')
index = pc.Index(host='hosturl')
# To iterate over all result pages using a generator function
for ids in index.list(prefix='pref', limit=3, namespace=namespace):
print(ids) # ['pref1', 'pref2', 'pref3']
# Now you can pass this id array to other methods, such as fetch or delete.
vectors = index.fetch(ids=ids, namespace=namespace)
There is also an option to fetch each page of results yourself with list_paginated.
from pinecone import Pinecone
pc = Pinecone(api_key='xxx')
index = pc.Index(host='hosturl')
namespace = 'foo-namespace'
# For manual control over pagination
results = index.list_paginated(
prefix='pref',
limit=3,
namespace='foo',
pagination_token='eyJza2lwX3Bhc3QiOiI5IiwicHJlZml4IjpudWxsfQ=='
)
print(results.namespace) # 'foo'
print([v.id for v in results.vectors]) # ['pref1', 'pref2', 'pref3']
print(results.pagination.next) # 'eyJza2lwX3Bhc3QiOiI5IiwicHJlZml4IjpudWxsfQ=='
print(results.usage) # { 'read_units': 1 }
We made an adjustment to our declared python version support (from python >=3.8,<3.13 to ^3.8) to make it easier for tools with more expansive statements on what python versions they support to include the pinecone sdk as a dependency. Alongside this change, we expanded our test matrix to include more robust testing with python versions 3.11 and 3.12. Python 3.13 is still in alpha and is not yet part of our test matrix.
Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v3.0.3...v3.1.0
gRPC: parse_query_response: Skip parsing empty Usage by @daverigby in https://github.com/pinecone-io/pinecone-python-client/pull/301
additional_headers with PINECONE_ADDITIONAL_HEADERS environment variable by @fsxfreak in https://github.com/pinecone-io/pinecone-python-client/pull/304Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v3.0.2...v3.0.3
This release resolves a bug when passing source_collection as part of the PodSpec. This option is used when creating a new index from vector data stor
source_collection option in PodSpecThis release resolves a bug when passing source_collection as part of the PodSpec. This option is used when creating a new index from vector data stored in a collection. The value of this field should be a collection you have created previously from an index and that shows with pc.list_collections(). Currently collections and pod-based indexes are not portable across environments.
from pinecone import Pinecone
pc = Pinecone(api_key='YOUR_API_KEY')
pc.create_index(
name='my-index',
dimension=1536,
metric='cosine',
spec=PodSpec(
environment='us-east1-gcp',
source_collection='collection-2024jan16',
)
)
GRPCClientConfig when using PineconeGRPCThis could be considered as a fix for a UX bug or a micro-feature, depending on your perspective. In 3.0.2 we updated the pc.Index helper method that is used to build instances of the GRPCIndex class. It now accepts an optional keyword param grpc_config. Before this fix, you would need to import GRPCIndex and instantiate GRPCIndex yourself in order to pass this configuration and customize some settings, which was a bit clunky.
from pinecone.grpc import PineconeGRPC, GRPCClientConfig
pc = PineconeGRPC(api_key='YOUR_API_KEY')
grpc_config = GRPCClientConfig(
timeout=10,
secure=True,
reuse_channel=True
)
index = pc.Index(
name='my-index',
host='host',
grpc_config=grpc_config
)
# Now do data operations
index.upsert(...)
pool_threads config on the index.Similar to the grpc_config option, some people requested the ability to pass pool_threads when targeting an index rather than in the initial client initialization. Now the optional configuration is accepted in both places, with the value passed to .Index() taking precedence.
Now these are both valid approaches:
from pinecone import Pinecone
pc = Pinecone(api_key='key', pool_threads=5)
pc.Index(host='host')
pc.upsert(...)
from pinecone import Pinecone
pc = Pinecone(api_key='key')
index = pc.Index(host='host', pool_threads=5)
index.upsert(...)
This is probably only relevant for internal Pinecone employees or support agents, but the index client now accepts configuration to attach additional headers to each data plane request. This can help with tracing requests in logs.
from pinecone import Pinecone
pc = Pinecone(api_key='xxx')
index = pc.Index(
host='hosturl',
additional_headers={ 'header-1': 'header-1-value' }
)
# Now do things
index.upsert(...)
The equivalent concept for PineconeGRPC is to pass additional_metadata. gRPC metadata fill a similar role as HTTP request headers, and should not be confused with metadata associated with vectors stored in your Pinecone indexes.
from pinecone.grpc import PineconeGRPC, GRPCClientConfig
pc = PineconeGRPC(api_key='YOUR_API_KEY')
grpc_config = GRPCClientConfig(additional_metadata={'extra-header': 'value123'})
index = pc.Index(
name='my-index',
host='host',
grpc_config=grpc_config
)
# do stuff
index.upsert(...)
grpc_config and pool_threads by @jhamon in https://github.com/pinecone-io/pinecone-python-client/pull/296additional_headers/additional_metadata to indexes by @jhamon in https://github.com/pinecone-io/pinecone-python-client/pull/297Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v3.0.1...v3.0.2
This release adds improved error messages to help guide people on how to address some of the breaking changes in v3, such as the migration of core fun…
This is a quick follow-up to the v3.0.0 release earlier this week. This release adds improved error messages to help guide people on how to address some of the breaking changes in v3, such as the migration of core functionality from attributes on the pinecone module into methods of the Pinecone class.
If you're updating from v2.2.x from the first time, you will still want to checkout the v3.0.0 Migration Guide for a walkthrough of all the new features and changes. All of that information is still accurate for this release.
Refactored urllib3 usage to stop spamming deprecation warning messages.
Serverless indexes are currently in public preview, so make sure to review the current limitations and test thoroughly before using in production.
create_index method has been refactored to accept a PodSpec or ServerlessSpec depending on how you would like to deploy your index. Many old properties such as pod_type, replicas, etc are moved into PodSpec since they do not apply to serverless indexes.query and fetch call are now returned with the response.https://api.pinecone.io/. This new API allows for a lot more flexibility in how API keys are used in comparison to the past when a rigid 1:1 relationship was enforced between projects and environments.pinecone.init into new Pinecone class instances that encapsulate their configuration state. This change enables users to interact with Pinecone using multiple API keys if they wish.numpy, pyyaml, loguru, requests, dnspythonurllib3 support back to 1.26.xpinecone.grpc, so that GRPC code is only imported when needed. For applications using REST, this will mean quicker startup and fewer dependency clashes with other packages.list_indexes and list_collections methods now return an array with full descriptions of each resource, not merely an array of names.DateTime objects.urllib3 usage to stop spamming deprecation warning messages.tqdm warning that was appearing during notebook runs.list_indexes now returns additional data, and to continue iterating over an array of names you need to chain a call to a new helper method .names(). See here.list_collections has changed very similar to list_indexes. Use .names(). See here.describe_index takes the same arguments as before (the index name), but returns data in a different shape reflecting the move of some configurations under the spec key and elevation of host to the top level. See a table of changed properties here.query method has been updated to reflect that top_k is a required parameter. If you previously relied on passing your query vector as the first positional argument, you’ll see a strange error from the API about duplicate top_k values being passed. We recommend adopting keyword arguments to fix and be resilient to any future changes, e.g. index.query(vector=vec, top_k=10)query() no longer accepts multiple queries via the queries keyword argument.PINECONE_DEBUG_CURL='true'Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v2.2.4...v3.0.0.dev10
Fixing annoying urllib3 deprecation error
environment kwarg mispelled by @tdonia in https://github.com/pinecone-io/pinecone-python-client/pull/198Full Changelog: https://github.com/pinecone-io/pinecone-python-client/compare/v2.2.2...v2.2.4
Nothing published for this version
numpy dependency from unpinned to >=1.22.0 to address low severity CVE-2021-34141
numpy dependency from unpinned to >=1.22.0 to address low severity CVE-2021-34141protobuf dependency from 3.19.3 to ~=3.19.5 to address a potential denial-of-service vector. This should only affect those consuming the grpc-flavored version of the client via pinecone-client[grpc].We plan to remove our dependency on numpy in a future release to simplify the install experience. Deprecation warnings have been added to code paths where numpy is currently in use. Let us know if you have concerns about this.
We have also removed support for Python 3.7 which has reached the official end-of-life. The last version of the pinecone-client to support Python 3.7 is v2.2.1. Our numpy dependency forced our hand in this decision to drop support because numpy 1.22.0 no longer supports Python 3.7.
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →