Skip to main content

CLI tool to solve problems of competitive programming

Project description

Online Judge Tools

test Documentation Status PyPI Downloads PyPI Join the chat at

Tools to help solving problems on various online judges. This automates downloading sample cases, generating additional test cases, testing for your code, and submitting it.




  • Download sample cases
  • Download system test cases
  • Login
  • Submit your code
  • Test your code
  • Test your code for reactive problems
  • Generate input files from generators
  • Generate output files from input and reference implementation

Many online judges (Codeforces, AtCoder, HackerRank, etc.) are supported. For details, see the table of online-judge-tools/api-client.

How to install

The package is PyPI.

$ pip3 install online-judge-tools

For detailed instructions, read the FAQ.

How to use

$ oj download [--system] URL
$ oj login URL
$ oj submit [URL] FILE
$ oj test [-c COMMAND] [TEST...]
$ oj test-reactive [-c COMMAND] JUDGE_COMMAND
$ oj generate-input GENERATOR_COMMAND
$ oj generate-output [-c COMMAND] [TEST...]

For details, see $ oj --help.


$ oj download
[+] problem recognized: <onlinejudge.atcoder.AtCoder object at 0x7f2925a5df60>
[x] GET:
[+] 200 OK

[*] sample 0
[x] input: 入力例 1
1 3 1 2
[+] saved to: test/
[x] output: 出力例 1
[+] saved to: test/sample-1.out

[*] sample 1
[x] input: 入力例 2
100 1 2 3 14 15 58 58 58 29
[+] saved to: test/
[x] output: 出力例 2
[+] saved to: test/sample-2.out

[*] sample 2
[x] input: Sample Input 1
1 3 1 2
[+] saved to: test/
[x] output: Sample Output 1
[+] saved to: test/sample-3.out

[*] sample 3
[x] input: Sample Input 2
100 1 2 3 14 15 58 58 58 29
[+] saved to: test/
[x] output: Sample Output 2
[+] saved to: test/sample-4.out


I cannot install online-judge-tools. What is $ pip3 install online-judge-tools? Please help!

Do following steps.

  1. If you use a Windows environment, use Windows Subsystem for Linux (WSL). For beginners, Linux (especially, Ubuntu) is often easier than Windows.
    • Also, if you use Visual Studio Code (or other IDEs), close it and forget it for a while. Don't use consoles in IDEs.
  2. :snake: Install Python. If you use Ubuntu (including Ubuntu in WSL), run $ sudo apt install python3.
  3. Check your Python with running $ python3 --version. If it says Python 3.x.y, it's OK.
    • If it says something like Command 'python3' not found, you have failed to install Python.
    • If the version of Python is too old, it's not OK. The x must be greater than or equal to 5. If x is lower than 5, upgrade your Python.
  4. :package: Install pip. If you use Ubuntu (including Ubuntu in WSL), run $ sudo apt install python3-pip.
  5. Check your pip with running $ pip3 --version. If it says something like pip x.y.z ..., it's OK.
    • If it says something like Command 'pip3' not found, you have failed to install pip.
    • Even if pip3 is not found, you may be able to use python3 -m pip instead of pip3. Try $ python3 -m pip --version. If it says pip x.y.z ..., it's OK.
    • Don't use pip or pip2. Use pip3.
  6. :dart: Run $ pip3 install online-judge-tools to install online-judge-tools. If it says Successfully installed online-judge-tools-x.y.z (or, Requirement already satisfied: online-judge-tools), it's OK.
    • If it says Permission denied, run $ sudo pip3 install online-judge-tools or $ pip3 install --user online-judge-tools.
  7. Check online-judge-tools with $ oj --version. If It must say something like online-judge-tools x.y.z.
    • If it says something like Command 'oj' not found, you need to set PATH.
      1. Find the path of the oj file with running $ find / -name oj 2> /dev/null. The file is often at /home/ubuntu/.local/bin/oj or /usr/local/bin/oj.
      2. Check the found oj file is actually oj, with running $ /home/ubuntu/.local/bin/oj --version.
      3. Add the directory which contains the oj to your PATH. For example, if oj is /home/ubuntu/.local/bin/oj, write export PATH="/home/ubuntu/.local/bin:$PATH" in the end of ~/.bashrc.
        • Don't write export PATH="$PATH:/home/ubuntu/.local/bin/oj". It's not a directory.
        • If you don't use bash, write a right settings to the right file depending on your shell. For example, if you use Mac OS, your shell might zsh. For zsh, write the same command to ~/.zshrc.
      4. Reload the configuration with source ~/.bashrc.
        • If you don't use bash, use an appropriate way.
      5. Check your PATH with $ echo $PATH. If it says /home/ubuntu/.local/bin:..., it's OK.
    • If it says something like ModuleNotFoundError: No module named 'onlinejudge', you have failed to install online-judge-tools and your environment is broken. Run $ pip3 install --force-reinstall online-judge-tools to reinstall.
    • If it says something like SyntaxError: invalid syntax, you have used pip2 by mistake. Run $ pip2 uninstall online-judge-tools, and retry to install.
  8. That's all.

If you couldn't read many sentences of above instructions (e.g. if you didn't know what "run $ python3 --version" means), please ask your friends for help. If you cannot install online-judge-tools even following the instructions, please add comments to this issue.

Other questions

  • I usually make one directory per one contest (or, site). Can I keep using this style?
    • Yes, you can use the --directory (-d) option or $ rm -rf test/. However, we don't recommend this style, because you should make additional test cases by yourself and run stress tests to maximize your rating.
  • Can I download all sample cases of all problems at once?
  • Can I automatically compile my source code before testing?
    • Yes, use your shell. Run $ g++ main.cpp && oj t.
  • Can I automatically submit code after it passes tests?
    • Yes, use your shell. Run $ oj t && oj s main.cpp. By the way, you need to take care of problems whose sample cases are not so strong.
  • Can I remove the delays and the [y/N] confirmation before submitting code?
    • Yes, put --wait=0 option and --yes option to oj s subcommand. Of course, we don't recommend this. They exist for failsafe. For example, please consider a situation where if you save 3 seconds, you will move up 3 places on the standings. In such a case, if you get a penalty of 5 minutes, then you will move down at least 300 places on the standings.
  • Can I clear my download history to omit the URL of the problem to submit?
    • Yes, remove the history file, whose name is download-history.jsonl.
  • Is my password stored?
  • Can I specify problems by their IDs or names, instead of URLs?
    • No. It may sound nice, but actually, hard to use and maintain.
  • Does the config file exist?
    • No. You can use your .bashrc (or similar files) instead. It's a config file of your shell. Read man bash and write shell aliases or shell functions. For example, if you want to use Python code for tests by default, write alias oj-test-python='oj t -c "python3"' (alias) to .bashrc and use $ oj-test-python, or write function oj-test-python() { FILE="$1" ; shift ; oj t -c "python3 '$FILE'" "$@" ; } (function) and use oj-test-python

For other questions, use Gitter Join the chat at or other SNSs.

Related Tools


not conflicted:

projects depending on kmyk/online-judge-tools:

  1. wrappers:
    • Tatamo/atcoder-cli is a thin wrapper optimized for AtCoder
    • kjnh10/pcm is a tool which internally uses online-judge-tools
    • some people use oj via Visual Studio Code
  2. libraries using this for CI:
  3. others:




For the full list of contributors, see or the contributors page of GitHub.



MIT License

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for online-judge-tools, version 10.0.3
Filename, size File type Python version Upload date Hashes
Filename, size online_judge_tools-10.0.3-py3-none-any.whl (37.2 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page