
Summarize with AI
How to Build a Custom XBlock for Open edX
Key takeaways:
- An Open edX XBlock is a self-contained Python component that adds new content or activity types to a course.
- Custom XBlocks are written in Python, with HTML, CSS, and JavaScript for the learner interface.
- Fields with the right scope decide what data is stored per learner, per course, or across all learners.
- Tutor installs custom XBlocks as Python packages, and Studio’s Advanced Module List makes them available to course teams.
- Testing against each named release, currently Verawood, keeps a custom XBlock working through platform upgrades.
Introduction
An Open edX XBlock is the building block behind every unit in an Open edX course, from video players to problem types. When the built-in components cannot deliver a specific activity, such as a branching simulation or a custom assessment, a custom XBlock fills the gap without changing the core platform.
Scale is what makes this useful. According to Open edX, the platform has reached more than 100 million learners across over 70,000 courses. Every one of those courses is assembled from XBlocks, so a well-built custom block can be reused across many courses and sites.
This XBlock tutorial explains how XBlocks work, then walks through building, installing, testing, and maintaining one. It closes with practical notes on compatibility and cost.
What an Open edX XBlock is
XBlock is the component framework that both the LMS and Studio use to render course content. Each XBlock is a Python class packaged as a library and registered with the platform through an entry point. As a result, new Open edX learning components can be added through Open edX plugin development rather than by forking the platform code.
Every XBlock has four main parts:
- Fields: Typed attributes that store data, such as a question text or a learner’s score.
- Views: Methods such as student_view and studio_view that return the HTML, CSS, and JavaScript a user sees.
- Handlers: Server-side methods that receive AJAX calls from the browser, for example when a learner submits an answer.
- Runtime: The host environment (LMS, Studio, or the SDK workbench) that saves field data and serves the views.
Field scope is the concept most worth understanding early. It decides who a value belongs to:
| Scope | Stored for | Typical use |
|---|---|---|
| Scope.content | The block, shared by all learners | Question text, instructions |
| Scope.settings | The block, editable by authors | Display name, attempt limits |
| Scope.user_state | Each learner, per block | A learner's answer or score |
| Scope.user_state_summary | All learners, per block | Aggregated poll results |
When to build a custom XBlock
The Open edX community already maintains many XBlocks, including drag-and-drop, LTI, and video options. Therefore, it makes sense to check existing packages before writing new code. Custom XBlock development is worth it in cases like these:
- Unique interactions: Simulations, labs, or games that standard problem types cannot model.
- External integrations: Embedding a proprietary tool, data feed, or assessment engine inside a unit.
- Branded experiences: Course designs that need consistent custom layouts across many courses.
- Specific grading logic: Scoring rules that must report grades back to the gradebook.
For broader Open edX course customization, such as theming or new learner dashboards, other extension points like plugin slots and micro frontends often fit better. Teams weighing these options frequently work with specialist Open edX development services to choose the right approach.
How to build an XBlock in Open edX
This custom XBlock tutorial builds a simple poll that asks learners a yes or no question and shows live results. The same pattern applies to more complex components.
Step 1: Set up the environment
XBlock Python development needs a recent Python 3 version that matches the target Open edX release, plus Git and a virtual environment. Install the XBlock SDK, which includes a lightweight workbench for local testing:
python -m venv venv && source venv/bin/activate
pip install xblock-sdk cookiecutterStep 2: Generate the project
The Open edX cookiecutter template creates the folder structure, packaging files, and test setup:
cookiecutter https://github.com/openedx/edx-cookiecutters --directory cookiecutter-xblockThe template produces a Python package with a static folder for HTML, CSS, and JavaScript, along with a setup.py or pyproject.toml file.
Step 3: Define fields and the learner view
The XBlock class declares its data and renders the learner interface:
from importlib.resources import files
from web_fragments.fragment import Fragment
from xblock.core import XBlock
from xblock.fields import Boolean, Dict, Scope, String
class PollXBlock(XBlock):
question = String(default="Was this unit useful?", scope=Scope.settings)
tally = Dict(default={"yes": 0, "no": 0}, scope=Scope.user_state_summary)
voted = Boolean(default=False, scope=Scope.user_state)
def resource(self, path):
return files(__package__).joinpath(path).read_text(encoding="utf-8")
def student_view(self, context=None):
frag = Fragment(self.resource("static/html/poll.html").format(self=self))
frag.add_css(self.resource("static/css/poll.css"))
frag.add_javascript(self.resource("static/js/poll.js"))
frag.initialize_js("PollXBlock")
return fragStep 4: Add a handler for learner actions
Handlers receive data from the browser and update fields:
@XBlock.json_handler
def vote(self, data, suffix=""):
choice = data.get("choice")
if not self.voted and choice in self.tally:
self.tally[choice] += 1
self.voted = True
return {"tally": self.tally}The JavaScript calls this handler through the runtime:
function PollXBlock(runtime, element) {
const url = runtime.handlerUrl(element, "vote");
$(".vote-btn", element).on("click", function () {
$.post(url, JSON.stringify({ choice: $(this).data("choice") }))
.done((res) => $(".results", element).text(`Yes: ${res.tally.yes} | No: ${res.tally.no}`));
});
}Step 5: Register the entry point
The platform finds XBlocks through the xblock.v1 entry point in the package configuration:
entry_points={"xblock.v1": ["poll = poll:PollXBlock"]}Step 6: Install it with Tutor
Most current deployments run on Tutor. Add the package to the build, rebuild the image, and restart the platform:
tutor config save --append OPENEDX_EXTRA_PIP_REQUIREMENTS=git+https://github.com/your-org/xblock-poll.git
tutor images build openedx
tutor local launchNext, open the course in Studio, go to Settings > Advanced Settings, and add “poll” to the Advanced Module List. The poll then appears under the Advanced component menu, which means custom XBlocks can be added to existing courses without rebuilding them.
How to test and debug a custom XBlock
Testing happens in layers, moving from fast local checks to a full platform environment:
- Workbench preview: The XBlock SDK workbench renders the block in a browser through scenarios defined in the workbench_scenarios method, which makes layout and handler bugs quick to spot.
- Unit tests: Pytest tests can call handlers directly and confirm that fields update correctly for each scope.
- Integration tests: Running the block in tutor dev checks real LMS and Studio behaviour, including grading and permissions.
- Debugging: Browser developer tools show JavaScript and network errors, while tutor dev logs reveals Python exceptions from handlers.
It also helps to test accessibility and mobile layouts early, because learners on the Open edX mobile apps may load the same unit. When in-house Python and Django skills are limited, teams often hire Open edX developers who already know the platform’s runtime and testing tools.
Keeping XBlocks compatible across releases
Open edX ships two named releases each year. According to the Open edX release notes, Verawood is the 22nd community release and launched on 30 July 2026, with Willow scheduled for December 2026. Each release can update Python, Django, and frontend dependencies.
A few practices keep Open edX XBlock development stable over time:
- Pin and test: Run the test suite against each new release before upgrading production.
- Avoid private imports: Rely on the public XBlock API rather than internal platform modules, which change without notice.
- Watch the frontend shift: Newer Open edX releases move authoring and learner pages to React-based micro frontends, so check how the block renders in new Studio and learning pages.
- Version the package: Tag releases so each platform version installs a known, tested build.
What custom XBlock development costs
Cost depends on interaction complexity, grading needs, external integrations, and how many Open edX versions the block must support.
A simple display component takes far less effort than an interactive learning component for Open edX that grades learners and syncs with outside systems.
For a fuller picture of platform budgeting, see this guide to Open edX implementation cost.
XBlocks are often one part of larger Open edX LMS development work, such as integrations, reporting, or a custom LMS development project.
Conclusion
An Open edX XBlock lets a course team add new activities without touching the core platform. Clear field scopes and small handlers keep the code easy to follow, and Tutor makes installation repeatable.
After that, the main job is testing against each named release. Most teams get the best results by shipping one focused component first and adding features once learners have used it.
FAQs
Similar Blogs


Hire Open edX Engineers: Tutor, DevOps & Technical Skills

Open edX vs Moodle vs Canvas for Corporate Training

How To Execute A Secure Moodle To Open edX Migration?





