Install & Compatibility
Where this runs
tested against v5.3.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.95 runs
installs and imports cleanly · install 0.0s · import 0.742s · 32.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.678s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
API
✓ from openfoodfacts import API
The primary class for interacting with the Open Food Facts API. Other specific modules like APIVersion, Country, etc., can be imported for advanced configuration.
Instantiate the API client with a mandatory user agent, then retrieve product details by barcode or perform a text search. For write operations, authentication (username and password) is required.
import os
from openfoodfacts import API
# User-Agent is mandatory for API calls
# It's recommended to include your application name and version
user_agent = os.environ.get('OPENFOODFACTS_USER_AGENT', 'MyAwesomeApp/1.0 - (https://example.com/myapp)')
api = API(user_agent=user_agent)
# Get information about a product by barcode
product_code = "3017620422003" # Example: Nutella
product_info = api.product.get(product_code, fields=["code", "product_name", "nutrition_grades", "ingredients_text"])
print(f"Product Name: {product_info.get('product', {}).get('product_name')}")
print(f"Nutri-Score: {product_info.get('product', {}).get('nutrition_grades')}")
# Perform a text search
search_results = api.product.text_search("mineral water")
print(f"Found {search_results.get('count')} products for 'mineral water'.")
if search_results.get('products'):
print(f"First result: {search_results['products'][0].get('product_name')}")
Debug
Known issues
gotchaThe SDK is currently in beta, and the underlying API is subject to change. It is highly recommended to pin the exact version of `openfoodfacts` in your `requirements.txt` to avoid unexpected breaking changes.fixAlways pin the library version (e.g., `openfoodfacts==5.0.1`) and review release notes before updating.
affects: All versions, especially from 3.x onwards
breakingVersion 5.0.0 introduced breaking changes related to improvements in the `ImageClassifier` module. If you were using image classification functionalities, your code might require updates.fixReview the official GitHub release notes and SDK documentation for `ImageClassifier` changes when upgrading to v5.0.0 or later.
affects: >=5.0.0
breakingVersion 4.0.0 included a breaking change related to `warnings.deprecated` being exclusively available on Python 3.13+. If your application used `warnings.deprecated` in conjunction with the SDK on Python versions older than 3.13, you might encounter issues.fixEnsure your Python environment is >=3.10 as required by the library. If relying on `warnings.deprecated` features, verify compatibility with Python 3.13+.
affects: >=4.0.0
gotchaA `user_agent` is a mandatory parameter when instantiating the `API` object. This helps Open Food Facts identify usage and contact you if necessary.fixAlways provide a descriptive `user_agent` string when initializing `openfoodfacts.API()`, e.g., `API(user_agent='YourAppName/1.0 - (https://your-app-website.com)')`.
affects: All versions
gotchaThe API should not be used for downloading large amounts of data (e.g., the entire database). For bulk data access, Open Food Facts provides daily data dumps (CSV, JSONL, MongoDB dumps) that should be used instead.fixFor bulk data, refer to the Open Food Facts 'Reusing Data' documentation to access data dumps. Use the API only for real-time product lookups or user contributions.
affects: All versions
gotchaWriting data (e.g., creating or updating products) to Open Food Facts requires authentication. You must provide a valid `username` and `password` when instantiating the `API` object.fixInitialize the API with authentication: `api = API(user_agent="...", username=os.environ.get('OFF_USERNAME'), password=os.environ.get('OFF_PASSWORD'))`. affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'openfoodfacts'
The 'openfoodfacts' package is not installed in the current Python environment or is not accessible from where the script is being executed.
fixInstall the library using pip: `pip install openfoodfacts`
KeyError: 'products'
The expected key, such as 'products', is missing from the dictionary returned by the Open Food Facts API, often due to an empty or error response, or a change in the API's data structure.
fixVerify the API response structure, handle missing keys gracefully using dictionary's `.get()` method, or implement `try-except KeyError` blocks.
AttributeError: 'API' object has no attribute 'product'
The 'product' attribute (or another sub-module/method) is being accessed on the main 'API' object before it has been properly initialized, or if the library's API structure has changed in a new version.
fixEnsure the `openfoodfacts.API` object is correctly instantiated and that you are calling valid methods or attributes according to the library's current documentation. For example: `api = openfoodfacts.API(user_agent="MyCustomApp/1.0")` followed by `api.product.get(...)`.
TypeError: 'NoneType' object is not subscriptable
This typically occurs when attempting to access elements (like `data['key']`) of an object that is `None`, which often happens if an API call or data retrieval method returns `None` instead of a dictionary or list when no data is found or an error occurred.
fixBefore attempting to access elements of an API response, check if the response object is `None` or empty. Implement conditional checks or provide default values.
requests.exceptions.HTTPError: 404 Client Error: Not Found for url:
The Open Food Facts API endpoint or a specific resource requested (e.g., a product with a given barcode) was not found on the server, indicating an incorrect URL, an invalid product code, or a non-existent resource.
fixVerify the barcode or product code being queried, check the exact API endpoint URL against the Open Food Facts API documentation, and ensure all required parameters are correctly passed in the request.
Upgrade
Version history
5.3.0latest on PyPI · released Jul 7, 2026
Audit
Dependencies
pillowoptionalRequired for image processing features (e.g., OCR, image classification).
redisoptionalRequired if using Redis caching features.