Install & Compatibility
Where this runs
tested against v3.11.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.697s · 21.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.3s · import 0.648s · 22MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Solr
✓ import pysolr
solr = pysolr.Solr('http://localhost:8983/solr/')
The primary class for interacting with a Solr instance.
This quickstart demonstrates how to connect to a Solr instance, index documents, perform a search, and delete documents. It uses `os.environ.get` for the Solr URL to support flexible deployment, defaulting to a local Solr instance. Note the use of `always_commit=True` due to a significant change in default behavior in recent versions.
import os
import pysolr
solr_url = os.environ.get('SOLR_URL', 'http://localhost:8983/solr/')
try:
# Connect to Solr with explicit commit behavior
solr = pysolr.Solr(solr_url, always_commit=True, timeout=10)
# Do a health check
solr.ping()
print(f"Successfully connected to Solr at {solr_url}")
# Index some data
docs_to_add = [
{"id": "doc_1", "title": "The Quick Brown Fox"},
{"id": "doc_2", "title": "Jumps Over The Lazy Dog"},
]
solr.add(docs_to_add)
print("Added documents.")
# Search for data
results = solr.search('fox')
print(f"Found {len(results)} result(s) for 'fox':")
for result in results:
print(f" - ID: {result['id']}, Title: {result['title']}")
# Delete a document
solr.delete(id='doc_1')
print("Deleted doc_1.")
# Search again to confirm deletion
results_after_delete = solr.search('fox')
print(f"Found {len(results_after_delete)} result(s) for 'fox' after deletion.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingPySolr has progressively dropped support for older Python versions. As of v3.9.0, Python 3.4 support was dropped. With v3.11.0, support for Python 3.9 and below has been explicitly removed. PySolr now strictly requires Python >=3.10.fixEnsure your Python environment is running version 3.10 or newer before upgrading to recent PySolr versions.
affects: >=3.9.0 (for Python 3.4), >=3.11.0 (for Python <=3.9)
breakingThe default commit behavior for add/delete operations changed significantly in v3.8.1. Previously, these operations would implicitly commit changes to Solr. From v3.8.1 onwards, `always_commit` defaults to `False` for performance. This means changes are buffered and not immediately searchable unless explicitly committed.fixTo maintain immediate indexing, initialize the Solr client with `pysolr.Solr(..., always_commit=True)`, or explicitly pass `commit=True` to individual `add()` or `delete()` calls (e.g., `solr.add(docs, commit=True)`). Alternatively, configure Solr's `autoCommit` or `commitWithin` policies.
affects: >=3.8.1
gotchaPySolr v3.9.0 introduced a JSON interface which can offer significantly faster data loading (up to 15-20 times faster) compared to the older XML-based conversion. Users may inadvertently stick to less performant methods.fixReview your Solr configuration and PySolr usage to ensure you are leveraging the JSON interface for optimal performance, especially for bulk indexing. PySolr handles JSON conversion automatically when passing Python dicts/lists, but awareness of the underlying mechanism is beneficial.
affects: >=3.9.0
gotchaWhen using custom Solr request handlers (often with `use_qt_param=True`), the handler name specified in the PySolr URL must precisely match the configuration in `solrconfig.xml`, including any leading slashes (e.g., `/update`). If `use_qt_param` is `False` (the default), leading/trailing slashes can be omitted.fixCarefully verify the Solr core URL and handler names, especially when moving between different Solr configurations or custom handlers. Consult your Solr `solrconfig.xml` for exact handler path specifications.
affects: All versions
deprecatedAs part of the shift to Python 3, PySolr v3.11.0 explicitly removed the Python 2 tag from its distribution metadata. While Python 2 compatibility was waning in earlier 3.x releases, this action definitively signals the end of any remaining support. Attempting to use newer PySolr versions with Python 2 tooling or environments may lead to installation failures or runtime errors.fixEnsure all development and deployment environments are standardized on Python 3.10 or newer. Update any dependency management or CI/CD configurations that might implicitly assume Python 2 compatibility.
affects: >=3.11.0
Upgrade
Version history
3.11.0latest on PyPI · released Nov 18, 2025
Audit
Dependencies
requestsrequiredRequired for HTTP communication with Solr.
kazoooptionalOptional dependency for SolrCloud awareness and ZooKeeper integration.
simplejsonoptionalOptional dependency for enhanced JSON support, particularly in older versions or specific use cases.