moodle-dl turns a Moodle account into an offline course library

Why a student wants a local copy of the course

moodle-dl is a console application that downloads all the files from your Moodle courses that are necessary for your daily study routine, and it can also notify you about various activities on your Moodle server. The project puts the motivation bluntly in its header, because manually downloading all the course files every few days is inefficient.

The audience is students, and specifically students who are enrolled in a course with a lot of material and who want it available offline. The tool keeps a local copy, skips what it already has, and tells you when something new appears. That combination is the whole product.

Two behaviours define it. Running moodle-dl again only downloads files that have not been downloaded yet, and if files are deleted online they are still available offline. The second point is the one that changes how you think about the tool, since the local copy becomes an archive rather than a cache.

Scope also extends past enrolment. It is possible to download Moodle courses you are enrolled in, as well as courses that are publicly visible to you, and the configuration wizard documents how to add extra visible courses you are not enrolled in.

The project is a Python package on PyPI, licensed GPL-3.0, with the console entry point defined in its metadata:

moodle-dl = "moodle_dl.main:main"

The last push was on 2026-06-20, and the tagged releases are older, with 2.3.13 on 2024-11-05, 2.3.12 on 2024-10-09 and 2.3.11 on 2024-07-04, the last of which activated the TLS ALPN extension.

What actually gets downloaded

The list of what the tool fetches is long, and it covers most of what a Moodle course contains.

Files come first, and then assignments including submissions, books, calendar events, forums, workshops, lessons, quizzes and descriptions. External links are also handled, and the documentation names the services involved, including OpenCast, YouTube, Sciebo, Owncloud, Kaltura, Helixmedia and Google Drive, for videos and files that live outside the Moodle installation.

The tool also grabs the text of your courses, such as pages, descriptions and forum posts, and attaches that text directly to the notifications, so you can read it in your messaging app without opening the course.

External material is a separate switch, because pulling a video from a third party is different from pulling a PDF from the course. The wizard can decide whether external files should be downloaded, and it can also decide whether files on Moodle that require a cookie should be fetched, which is the difference between a course you can read anonymously and one that needs your session.

The wizard covers nearly all of the settings. You select the courses to download, rename each course individually, choose whether subfolders are created inside a course folder, and decide for each content type, submissions, descriptions, links inside descriptions, databases, quizzes, lessons, workshops and forum discussions, whether it should be downloaded. The documentation notes that not every setting is exposed in the command line wizard and points to the wiki for the fuller list of options.

The mobile API is the hard dependency

Everything rests on one thing, and the project states it without hedging: moodle-dl uses the Moodle mobile API. If your Moodle does not allow access via the Moodle app, moodle-dl will not be able to connect to your Moodle.

That is an unusual constraint for a downloader, and it is a good one to understand before installing anything. Institutions that lock down mobile access, often for security policy reasons, will also lock out this tool, and no amount of local configuration will change that.

The login flow is built around tokens rather than stored credentials. The documentation says the login information for your Moodle account is secure and is not saved in any way, and that only a login token is saved. That token lives in the configuration file, config.json, and the notes section warns you to make sure no unauthorised person can read that file, particularly the token.

The initial configuration is created with moodle-dl --init, which starts a command line wizard. There are variations for institutions that use single sign-on, with the --sso option for something like Shibboleth or OAuth2, and for automation you can pass --username and --password, or --token directly. If a previously saved token is rejected by Moodle, the documented fix is to run moodle-dl --new-token instead.

There is one more token, and it is different in kind. By default a private token is stored in the initial configuration, and it is only needed for special Moodle modules that cannot be queried through the Moodle API. If you have no such module, the documentation says you are welcome to delete it.

Notifications carry the course text with them

The notification side is what turns a downloader into something you keep running.

Notifications can be sent to Telegram, Discord, XMPP and mail. The current implementation covers notifications about all downloaded files, and the text from your courses, meaning pages, descriptions and forum posts, is attached directly to the notification so you can read it in the messaging app.

The configuration for the channels lives in the wizard as well, and the repository links a dedicated wiki page for Telegram notification setup. There is also a general instructions page for the rest.

The security note about notifications is the part to read before configuring any of them. The project advises using a separate email or XMPP account for sending out the notifications, because the login data for that account is saved in cleartext. That is a different risk profile from the Moodle token, which is stored but is the only thing stored, and it is worth taking the advice literally rather than pointing notifications at a primary mailbox.

The command that does the daily work is deliberately plain. After configuring moodle-dl, running the tool with no options is enough to download all the files from your Moodle account and notify you about the result.

A GUI, Docker, Homebrew and a repology badge

The distribution options are broader than a plain pip install, and the packaging metadata is where you can see them.

The project ships a Docker deployment, publishes a repology badge for the latest packaged versions and for the packaging status, has a Homebrew formula, and a Discord server alongside the GitHub issues where development is discussed. The repository itself carries a Dockerfile that installs the package with uv into a python:3 image, adds ffmpeg and starts the tool with a path argument:

FROM python:3

ENTRYPOINT ["moodle-dl", "--path", "/files"]

The optional graphical interface is worth a mention because it is a recent addition and it changes the audience. It covers login, course configuration, download management and settings, with no command line needed, and it is installed as an extra with the gui dependency:

gui = ["PySide6>=6.5.0"]

The interface is launched with moodle-dl --gui, and it requires PySide6 at version 6.5.0 or newer. If PySide6 is not installed, the documentation says the command prints a helpful error and exits rather than failing in a confusing way.

For the console path, the requirements are Python 3.8 or newer, ffmpeg, and a pip install of the package. Windows users get a specific warning: run it in PowerShell or CMD and not in a mintty such as MINGW, and the setup page explains when the Visual C++ build tools are needed to compile the dependencies.

Dependencies, build backend and what the wheel ships

The packaging is a hatchling project with a dynamic version, and the build metadata is short enough to read.

The build backend is hatchling, and the version is not written in the metadata but read from a file, with the tool configuration pointing at moodle_dl/version.py. The wheel target packages only the moodle_dl directory, and it has an explicit note about the compiled translation catalogues, the .qm files, being shipped as artifacts while the .ts sources stay out of the installed package.

The runtime dependencies describe the project accurately. For asynchronous network work there is aiohttp with aiodns for DNS and aiofiles for files, plus requests and certifi. For terminal output, colorama and colorlog. For turning HTML course pages into the plain text that goes into notifications, html2text. For interactive prompts in the wizards, readchar. For chat notifications, xmpppy. For video, yt_dlp, which is how the YouTube and similar external links get fetched. And sentry_sdk, which is how the project reports errors.

The development group is minimal, ruff for linting and pre-commit, and the repository carries a pre-commit configuration file and a uv.lock for reproducible installs.

The licence is GPL-3.0, which is worth noting for anyone thinking of bundling this into a script collection or wrapping it in a tool of their own, since the copyleft obligations attach to a distributed derivative.

Editorial conclusion

moodle-dl suits a student who wants a local copy of a course that keeps itself in sync and a message when something changes, and it is the wrong tool for a Moodle installation that blocks the mobile API, since the project states it cannot connect in that case. Before adopting it, confirm your instance allows access through the Moodle app, read the notes about cleartext notification credentials, and check the config.json file that holds the login token before you let it sit on a shared machine.

Frequently asked questions

Official sources

1. C0D3D3V/Moodle-DL on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases