Skip to main content

Show coverage stats online via

Project description is service to publish your coverage stats online with a lot of nice features. This package provides seamless integration with in your python projects. For ruby projects, there is an official gem. Only projects hosted on Github are supported.

Works with python 2.6+, 3.2+ and pypy 1.9.

Usage (Travis CI)

This library will publish your coverage results on for everyone to see (unless you’re using pro account). This package can possibly work with different CI environments, but it’s only tested to work with Travis CI atm.

  1. First, log in via Github and add your repo on Coveralls website.

  2. Add pip install coveralls to install section of .travis.yml

  3. Make sure you run your tests with coverage during the build in script part. Example:

    # --source specifies what packages to cover, you probably want to use that option
      coverage run --source=yourpackagename test

    Note, that example command will gather coverage for specified package. If you wish to customize what’s included in your reports, consult coverage docs.

  1. Execute run coveralls in after_success section:


Full example of .travis.yml:

language: python
  - 2.7
  - 3.3
  - pip install -r requirements.txt
  - pip install coveralls
  coverage run --source=moscowdjango,meetup test

Usage (another CI)

If you’re NOT using Travis, first option is to provide a repo_token option in .coveralls.yml at the root of your repo. This is your own secret token, which is available at the bottom of your repository’s page on Coveralls. Make sure it stays secret, do not put it in your public repo.

Example of .coveralls.yml:

# .coveralls.yml
repo_token: TjkDuVpGjuQcRhNW8dots9c8SSnv7ReM5

Another alternative is to use COVERALLS_REPO_TOKEN env variable.


Nosetests provide a plugin for coverage measurement of your code:

$ nosetests  --with-coverage --cover-package=<your_package_name>

However, it gathers coverage for all executed code, ignoring source config option in .coveragerc. It means, that coveralls will report unnecessary files, which is inconvenient. Here is a workaround, use omit option in your .coveragerc to specify a list of filename patterns, the files to leave out of reporting (your paths might differ)

omit =

Note, that native and py.test are not affected by this problem and do not require this workaround.

How it works

It makes custom report for data generated by package and sends it to json API of service. All python files in your coverage analysis are posted to this service along with coverage stats, so please make sure you’re not ruining your own security! For private projects there is Coveralls Pro.

Tips for .coveragerc config

This section is a list of most common options for, which collects all the data. Coveralls feeds from this data, so it’s good to know how to to configure

To limit the report with only your packages, specify their names (or directories):

source = pkgname,your_otherpackage

To exclude parts of your source from coverage, for example migrations folders:

omit = */migrations/*

Some lines are never executed in your tests, but that can be ok. To mark those lines use inline comments right in your source code:

if debug:   # pragma: no cover
    msg = "blah blah"
    log_message(msg, a)

Sometimes it can be tedious to mark them in code, so you can specify whole lines to .coveragerc:

exclude_lines =
    pragma: no cover
    def __repr__
    raise AssertionError
    raise NotImplementedError
    if __name__ == .__main__.:

Finally, if you’re using non-default configuration file, specify it to coveralls command:

$ coveralls --rcfile=<file>


In case your coverage is not submitted to, despite your best efforts to configure, you can use debug:

$ coveralls debug

Debug mode doesn’t send anything, just outputs prepared json and reported files list to stdout.


Run tests:

$ python test

Install latest unstable version:

$ pip install coveralls==dev
Bitdeli badge


0.4.2 (2014-05-05)

  • Handle 503 errors from

0.4.1 (2014-01-15)

  • Fix gitlog output with utf8

0.4 (2013-12-27)

  • Added support for –rcfile=<file> option to cli
  • Improved docs: nosetests and troubleshooting sections added
  • Added debug in case of UnicodeDecodeError
  • Removed sh dependency in favor of Windows compatibility

0.3 (2013-10-02)

  • Added initial support for Circle CI
  • Fixed Unicode not defined error in python 3

0.2 (2013-05-26)

  • Python 3.2 and PyPy support
  • Graceful handling of coverage exceptions
  • Fixed UnicodeDecodeError in json encoding
  • Improved readme

0.1.1 (2013-02-13)

  • Introduced COVERALLS_REPO_TOKEN environment variable as a fallback for Travis
  • Removed repo_token from verbose output for security reasons

0.1 (2013-02-12)

  • Initial release

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
coveralls-0.4.2-py2.py3-none-any.whl (13.5 kB) Copy SHA256 hash SHA256 Wheel 2.7 May 5, 2014 (17.2 kB) Copy SHA256 hash SHA256 Source None May 5, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page