Registry / serialization / itemloaders

itemloaders

JSON →
library1.4.0pypypi✓ verified 24d ago

Itemloaders is a base library for Scrapy's ItemLoader, providing a robust and flexible way to parse and populate Scrapy Items. It handles data extraction from various sources (XPath, CSS, regular expressions, JMESPath) and processes it through a chain of input and output processors. The current version is 1.4.0, and the library maintains an active release cadence, frequently updating Python version support.

pip install itemloaders
INSTALL
IMPORT
SIG · ITEMLOADERS
I
itemloaders
serializationpythonv1.4.0
Install
2.4s avg
Import
252ms
Disk
30MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.4.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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.262s · 31.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.4s · import 0.242s · 32MB
30MB installed
● package 30MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ItemLoader
from itemloaders import ItemLoader
TakeFirst
from itemloaders.processors import TakeFirst
MapCompose
from itemloaders.processors import MapCompose

This quickstart demonstrates how to define a simple Item, create an `ItemLoader` inheriting from `itemloaders.ItemLoader`, and use CSS selectors, XPath, and custom processors (`MapCompose`, `TakeFirst`) to extract and process data from an HTML string using `parsel.Selector` to populate the item fields.

import re from itemloaders import ItemLoader from itemloaders.processors import TakeFirst, MapCompose # A minimal Scrapy-like Item (often defined as scrapy.Item) class MyItem: def __init__(self, **kwargs): for k, v in kwargs.items(): setattr(self, k, v) def __repr__(self): return str(self.__dict__) # Define an ItemLoader for MyItem class ProductLoader(ItemLoader): default_item_class = MyItem default_output_processor = TakeFirst() name_in = MapCompose(lambda x: x.strip(), str.title) price_out = MapCompose(lambda x: x.replace('$', ''), float) description_in = MapCompose(lambda x: x.strip()) # Example HTML fragment html_data = ''' <div class="product"> <h1 class="name"> product a </h1> <span class="price">$12.99</span> <div class="description">A really good product.</div> </div> ''' # Using parsel.Selector for data extraction from parsel import Selector selector = Selector(text=html_data) # Instantiate the loader and populate the item loader = ProductLoader(selector=selector) loader.add_css('name', '.name::text') loader.add_xpath('price', '//span[@class="price"]/text()') loader.add_value('description', 'Short description from custom source.') # Add a fixed value loader.add_css('description', '.description::text') # Can add multiple sources for the same field # Load the item item = loader.load_item() print(item) # Expected output: {'name': 'Product A', 'price': 12.99, 'description': 'A really good product.'}
Debug
Known issues
breakingPython version compatibility has changed frequently, dropping support for older versions. For example, v1.4.0 dropped Python 3.8-3.9, v1.2.0 dropped Python 3.7, and v1.1.0 dropped Python 3.6.
fix
Ensure your project's Python version meets the minimum requirements for the `itemloaders` version you are using. Check the release notes for specific version requirements before upgrading.
affects: >=1.1.0
gotchaVersion 1.3.0 introduced a regression where nested loaders would raise an error when encountering empty matches.
fix
Upgrade to version 1.3.1 or newer, which includes a fix for this issue.
affects: 1.3.0
gotchaIn version 1.0.5, passing a compiled regular expression pattern (e.g., `re.compile('...')`) to the `re` parameter of methods like `ItemLoader.add_xpath` or `add_css` could cause an exception due to it being passed directly to `lxml`.
fix
Upgrade to version 1.0.6 or newer, which fixed this regression. If constrained to 1.0.5, ensure the `re` parameter is always a string pattern, or avoid using compiled patterns.
affects: 1.0.5
gotchaJMESPath support, introduced in v1.1.0 with methods like `ItemLoader.add_jmes`, requires `parsel` version 1.8.1 or newer. While `itemloaders` itself might declare a lower minimum `parsel` dependency, using JMESPath features necessitates the newer `parsel` version.
fix
If using JMESPath features, ensure your `parsel` dependency is explicitly set to `parsel>=1.8.1`.
affects: >=1.1.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'itemloaders'
The `itemloaders` library was split from Scrapy into its own package in Scrapy versions 2.3 and above, requiring a separate installation.
fix
pip install itemloaders
AttributeError: 'NoneType' object has no attribute 'load_item'
This error typically occurs when the ItemLoader object itself or the 'item' it's meant to populate is None, often because the ItemLoader was not correctly instantiated or did not receive a valid item or response to process.
fix
Ensure the ItemLoader is instantiated with a valid Scrapy Item or by setting `default_item_class` if creating an item automatically. Also, verify that the `response` or `selector` passed to the ItemLoader is not None.

Example:
from scrapy.loader import ItemLoader
from myproject.items import ProductItem

def parse(self, response):
    if response is None:
        self.logger.warning("Received a None response, skipping ItemLoader initialization.")
        return
    loader = ItemLoader(item=ProductItem(), response=response)
    # ... add_xpath, add_css, etc.
    yield loader.load_item()
RuntimeError: To use XPath or CSS selectors, ItemLoader must be instantiated with a selector
Methods like `add_xpath()` or `add_css()` require the `ItemLoader` instance to have an associated selector or response, which was not provided during its instantiation.
fix
Instantiate the `ItemLoader` with a `response` object or a `Selector` object.

Example:
from scrapy.loader import ItemLoader
from myproject.items import MyItem

def parse(self, response):
    loader = ItemLoader(item=MyItem(), response=response)
    # Now you can use add_xpath or add_css
    loader.add_xpath('name', '//h1/text()')
    yield loader.load_item()
TakeFirst() not working or returning a list instead of string
The `TakeFirst` processor is an output processor designed to take the first non-null value from an iterable. If it's used as an input processor or if there's a misunderstanding of how and when it applies, it might not yield the expected single string, or the field might still contain a list if the processor isn't correctly applied to the output stage.
fix
Ensure `TakeFirst()` is correctly assigned as an `_out` processor for a specific field or as the `default_output_processor` for the ItemLoader. Also, verify that the data reaching the output processor is indeed an iterable.

Example:
from itemloaders.processors import TakeFirst, MapCompose
from scrapy.loader import ItemLoader

class ProductLoader(ItemLoader):
    default_output_processor = TakeFirst() # Applies to all fields by default
    # Or for a specific field:
    name_out = TakeFirst()
    description_in = MapCompose(str.strip)
    description_out = Join()
Upgrade
Version history
1.4.0latest on PyPI · released Jan 29, 2026
Audit
Dependencies
parselrequiredRequired for parsing and selector functionality (XPath, CSS, JMESPath).
Agent activity
7 hits · last 30 days
node
6
Resources