Welcome to mal’s documentation!


mal is a command-line client for the official API of MyAnimeList.net website. It should remain functional indefinitely (it will never have web-scraping, unlike other alternative projects). It is currently in alpha development and new ideas are welcome! This project was initially inspired in mal.


  • Search your anime list
  • Fetch your anime list
  • List animes by their statuses (e.g. watching)
  • Increment or decrement seen episodes
  • Add animes to your watch list planner
  • Edit contents of your animes on your own preferred text editor: tags, status, score.
  • Print your MAL stats! Just like you do on MyAnimeList.

More features are currently being developed!


Using pip

From the command line run:

sudo pip install mal

Manual Installation

Clone this project and inside it run:

sudo python setup.py install

Or alternatively using make:

pip install --user .

mal requires super-user permissions when you run make install inside of a virtualenv. We strong encourage you to install it with pip install --user ..

On ArchLinux

mal has been packaged and uploaded to the AUR as python-mal-git in case you’re using an archlinux distro.

You may install it using an AUR wrappers such yaourt or pacaur, making the installation much simpler.

Using yaourt:

yaourt -S python-mal-git

Using pacaur:

pacaur -y python-mal-git

Or manually:

wget https://aur.archlinux.org/cgit/aur.git/snapshot/python-mal-git.tar.gz
tar xvzf python-mal-git.tar.gz
cd python-mal-git/
makepkg -si

Notice that all dependencies should be installed before using this method.



mal needs your credentials in order to access your anime list. In its first call to any valid command, it will ask for your username and password and save it in plain text its default path (on linux ~/.config/mal/myanimelist.ini).

The file will be saved in the following format:

username = your_username
password = your_password

You may start using mal after authenticating your user.

Using The Interface

When mal is executed without any arguments a help message is displayed:

usage: mal [-h]

MyAnimeList command line client.

positional arguments:
    search              search an anime
    increase (inc)      increase anime's watched episodes by one
    decrease (dec)      decrease anime's watched episodes by one
    login               save login credentials
    list                list animes
    config              config - not implemented yet
    download            download - not implemented yet
    watch               watch - not implemented yet

optional arguments:
  -h, --help            show this help message and exit

You can also use the -h or --help options on mal or any of its subcommands to see specific help messages.

Indices and tables