The last online dictionary framework you need. (?)
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Update pytest-flake8 to 1.0.4 (#309) Feb 17, 2019
ci [travis] enable macOS Jan 21, 2017
scripts Remove useless import and docstring. Oct 7, 2015
zdict Version 2.0.0 Feb 16, 2019
.dockerignore [#94] Add docker support. Jun 30, 2016
.gitignore Add JUnit test reports for pytest Oct 26, 2018
.pyup.yml Revert "[pyup.yml] Remove Pipfile.lock" Oct 14, 2018
.travis.yml [Travis CI] Add workaround for Travis CI stdout write error Dec 24, 2018
Dockerfile Create Aug 5, 2015 zdict-0.9.5: DaaS Jun 30, 2016
Pipfile Update pytest to 4.3.0 (#317) Feb 20, 2019
Pipfile.lock Update pytest to 4.3.0 (#317) Feb 20, 2019
README.rst Update README.rst Oct 30, 2018
requirements.txt Update peewee to 3.8.2 (#304) Jan 20, 2019
setup.cfg Add JUnit test reports for pytest Oct 26, 2018 Rename test-requirements.txt to requirements-test.txt Oct 26, 2018




travis circleci coveralls

license Join the chat at

Note: This project is working in progress.

zdict is a CLI dictionary framework mainly focus on any kind of online dictionary. This project originally forked from, which is a CLI tool for the Yahoo! online dictionary. After heavily refactoring the original project including:

  1. Change from Python 2 to Python 3
  2. Focus on being a flexible framework for any kind online dicitionaries, not only just a CLI tool for querying Yahoo! online dictionary.
  3. Based on an open source project skeleton.

So, we decided to create a new project.


from PyPI :

pip install zdict

from GitHub :

pip install git+

from Docker Hub :

# Pull the image of latest commit of master branch from Docker Hub
docker pull zdict/zdict

# Pull the image of latest release from Docker Hub
docker pull zdict/zdict:release

# Pull the image of specific release version from Docker Hub
docker pull zdict/zdict:${version}
docker pull zdict/zdict:v0.10.0

How to run the zdict docker image

# Run interactive mode
docker run -it --rm zdict/zdict         # latest commit
docker run -it --rm zdict/zdict:release # latest release
docker run -it --rm zdict/zdict:v0.10.0 # use zdict v0.10.0
docker run -it --rm zdict/zdict:$tag    # with specific tag

# Run normal mode
docker run -it --rm zdict/zdict apple bird         # latest commit
docker run -it --rm zdict/zdict:release apple bird # latest release
docker run -it --rm zdict/zdict:v0.10.0 apple bird # use zdict v0.10.0
docker run -it --rm zdict/zdict:$tag apple bird    # with specific tag

# You can also add the options while using docker run either interactive mode or normal mode
docker run -it --rm zdict/zdict:v0.10.0 -dt moe    # use moe dict in interactive mode
docker run -it --rm zdict/zdict:v0.10.0 -dt moe 哈 # use moe dict in normal mode


usage: zdict [-h] [-v] [-d] [-t QUERY_TIMEOUT] [-j [JOBS]] [-sp] [-su]
             [-dt spanish,yandex,moe,moe-taiwanese,yahoo,wiktionary,urban,jisho,oxford,all]
             [-ld] [-V] [-c] [--dump [PATTERN]] [-D]
             [word [word ...]]

positional arguments:
  word                  Words for searching its translation

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -d, --disable-db-cache
                        Temporarily not using the result from db cache. (still
                        save the result into db)
  -t QUERY_TIMEOUT, --query-timeout QUERY_TIMEOUT
                        Set timeout for every query. default is 5 seconds.
  -j [JOBS], --jobs [JOBS]
                        Allow N jobs at once. Do not pass any argument to use
                        the number of CPUs in the system.
  -sp, --show-provider  Show the dictionary provider of the queried word
  -su, --show-url       Show the url of the queried word
  -dt spanish,yandex,moe,moe-taiwanese,yahoo,wiktionary,urban,jisho,oxford,all, --dict spanish,yandex,moe,moe-taiwanese,yahoo,wiktionary,urban,jisho,oxford,all
                        Must be seperated by comma and no spaces after each
                        comma. Choose the dictionary you want. (default:
                        yahoo) Use 'all' for qureying all dictionaries. If
                        'all' or more than 1 dictionaries been chosen, --show-
                        provider will be set to True in order to provide more
                        understandable output.
  -ld, --list-dicts     Show currently supported dictionaries.
  -V, --verbose         Show more information for the queried word. (If the
                        chosen dictionary have implemented verbose related
  -c, --force-color     Force color printing (zdict automatically disable
                        color printing when output is not a tty, use this
                        option to force color printing)
  --dump [PATTERN]      Dump the querying history, can be filtered with regex
  -D, --debug           Print raw html prettified by BeautifulSoup for


Yahoo Dictionary

  • Normal Mode

zdict hello

  • Interactive Mode


Moe Dictionary 萌典

Urban Dictionary


Jisho Japanese Dictionary

Yandex Translate

Oxford Dictionary

To use this source, you should first apply an API key and place it under ~/.zdict/oxford.key in the format:

app_id, app_key


Development & Contributing


During development, you can install our project as editable. If you use virtualenv, you may want to create a new enviroment for zdict:

$ git clone
$ cd zdict
$ pip install -e .

Once you installed it with the command above, just execute zdict after modification. Don't need to install it again.

We use py.test:

$ pip install pytest pytest-cov coverage
$ python test


$ py.test

After runing testing, we will get a coverage report in html. We can browse around it:

$ cd htmlcov
$ python -m http.server

Also, there is some configs for py.test in setup.cfg. Change it if you need.


py.test can prompt pdb shell when your test case failed:

$ python test -a "--pdb"


$ py.test --pdb

Bug Report

Feel free to send a bug report to Please attach the error message and describe how to reproduce the bug. PR is also welcome.

Please use the -d/--disable-db-cache option to query before sending the bug report. Sometimes we modify the data schema in database for a dictionary, but the default dictionary query of zdict uses the cache in the database which may be stored within an old schema. This might cause an error while showing the result. Just use the -d/--disable-db-cache to update the cache in database.

Related Projects

  • zdict.vim
    • A vim plugin integrates with zdict.
    • A collection of shell completion scripts for zdict.

Stargazers over time