Open edX XBlock Core Library

6.1.0 verified Mon Apr 27 auth: no python

XBlock is the core library for the Open edX learning platform component architecture. It provides the framework for creating, managing, and rendering course content blocks with support for runtime integration, user state, and scoring. Current version is 6.1.0, with releases every few months.

pip install xblock

Common errors

error ImportError: cannot import name 'Fragment' from 'xblock.fragment' ↓

cause Fragment moved to web-fragments package in XBlock v4.0.0

fix

Install web-fragments and use 'from web_fragments.fragment import Fragment'

error TypeError: __init__() got an unexpected keyword argument 'runtime' ↓

cause XBlock subclasses should call super().__init__(**kwargs) and pass runtime as a keyword argument

fix

Ensure your XBlock __init__ accepts and forwards runtime: def __init__(self, runtime, *args, **kwargs): super().__init__(runtime, *args, **kwargs)

error AttributeError: 'MyBlock' object has no attribute 'scope_ids' ↓

cause XBlock requires scope_ids to be set by the runtime; usually from the definition or usage key

fix

Make sure the runtime provides a scope_ids attribute, or set it before accessing fields with user-specific scopes.

Warnings

breaking Fragment class moved from xblock.fragment to web_fragments.fragment in v4.0.0. The old import path still works via a compatibility shim but will be removed in a future release. ↓

fix Use 'from web_fragments.fragment import Fragment' instead of 'from xblock.fragment import Fragment'.

deprecated XBlock.runtime is deprecated. Use self.runtime instead. ↓

fix Access runtime via 'self.runtime' directly.

gotcha Scope.user_state is per-user, but if you want per-user per-block-instance you need Scope.user_state. Scope.preferences is deprecated. ↓

fix Use Scope.user_state for user-specific data that persists per block instance.

Imports

XBlock
wrong
```
from xblock import XBlock
```
correct
```
from xblock.core import XBlock
```
XBlock class is in xblock.core module, not top-level xblock
Fragment
wrong
```
from xblock.fragment import Fragment
```
correct
```
from web_fragments.fragment import Fragment
```
As of v4.0.0, Fragment moved to web-fragments package; old import still works but deprecated
Scope
```
from xblock.fields import Scope
```
String
```
from xblock.fields import String
```

Quickstart

Define a minimal XBlock with a student view and a JSON handler.

from xblock.core import XBlock
from xblock.fields import Integer, Scope
from web_fragments.fragment import Fragment

class SimpleBlock(XBlock):
    count = Integer(default=0, scope=Scope.user_state)

    def student_view(self, context=None):
        html = f'<p>Count: {self.count}</p>'
        return Fragment(html)

    @XBlock.json_handler
    def increment(self, data, suffix=''):
        self.count += 1
        return {'count': self.count}