Open edX Development 16 November 2026

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:

ScopeStored forTypical use
Scope.contentThe block, shared by all learnersQuestion text, instructions
Scope.settingsThe block, editable by authorsDisplay name, attempt limits
Scope.user_stateEach learner, per blockA learner's answer or score
Scope.user_state_summaryAll learners, per blockAggregated 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 cookiecutter

Step 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-xblock

The 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 frag

Step 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 launch

Next, 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.

Blog Talk to Open edX expert Blog

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.

Blog Book a consultation Blog

FAQs

An XBlock is a reusable Python component that renders course content such as videos, problems, or interactive activities. Open edX uses XBlocks in both the LMS and Studio to build every course unit.
Custom XBlocks use Python for fields, handlers, and server logic. HTML, CSS, and JavaScript build the learner and author interfaces, and some newer blocks also use React components.
Set up the XBlock SDK, generate a project from the cookiecutter template, then define fields, views, and handlers. Finally, register the entry point, install it with Tutor, and enable it in Studio.
Yes, once installed on the platform, a custom XBlock can be enabled per course through Studio's Advanced Module List. Course teams can then add it to existing units without rebuilding the course.
Custom XBlocks add interactions and integrations that built-in components cannot provide. They are reusable across courses and keep custom code separate from the core platform, which makes upgrades easier.
Use the XBlock SDK workbench for quick previews and pytest for unit tests. Then run the block in a Tutor development environment and check browser tools and server logs for errors.
Yes, if it relies on the public XBlock API and is tested against each named release. Dependency updates in Python, Django, or the frontend may still require small code changes.
Businesses can work with Open edX specialists who build, test, and maintain custom XBlocks. CodeTrade, an Open edX Partner, offers XBlock development as part of its Open edX services.
Author
Author

Chand Prakash

Chand Prakash founded CodeTrade India and continues to lead it as CTO, shaping the technical direction of the company since its early days. He has spent his career solving hard engineering problems and building teams that ship reliable software, with a focus on ERP, e-commerce, and custom enterprise platforms.