Skip to main content

Python interface for c-ares

Project description

Looking for new maintainers

pycares: Python interface for c-ares

pycares is a Python module which provides an interface to c-ares. c-ares is a C library that performs DNS requests and name resolutions asynchronously.


Bundled c-ares

pycares currently bundles c-ares as a submodule for ease of building. Using the system provided c-ares is possible if the PYCARES_USE_SYSTEM_LIB environment variable is set to 1 when building.

NOTE: Versions prior to 4.0.0 used to embed a modified c-ares with extended TTL support. That is no longer the case and as a result only A and AAAA records will have TTL information. Follow this PR in uppstream c-ares, looks like TTLs will be added:


GNU/Linux, macOS, Windows, others:

pip install pycares


cd /usr/ports/dns/py-pycares && make install

IDNA 2008 support

If the idna package is installed, pycares will support IDNA 2008 encoding otherwise the builtin idna codec will be used, which provides IDNA 2003 support.

You can force this at installation time as follows:

pip install pycares[idna]

Running the test suite

From the top level directory, run: python -m unittest -v

NOTE: Running the tests requires internet access and are somewhat environment sensitive because real DNS quesries are made, there is no mocking. If you observe a failure that the CI cannot reproduce, please try to setup an environment as close as the current CI.

Using it from the cli, a la dig

This module can be used directly from the command line in a similar fashion to dig (limited, of course):

$ python -m pycares
;                  IN      A

;; ANSWER SECTION:           300     IN      A

$ python -m pycares mx
;                  IN      MX

;; ANSWER SECTION:           600     IN      MX      50           600     IN      MX      10           600     IN      MX      40           600     IN      MX      20           600     IN      MX      30


Saúl Ibarra Corretgé <>


Unless stated otherwise on-file pycares uses the MIT license, check LICENSE file.

Supported Python versions

Python >= 3.8 are supported. Both CPython and PyPy are supported.


If you’d like to contribute, fork the project, make a patch and send a pull request. Have a look at the surrounding code and please, make yours look alike :-)

Project details

Download files

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

Source Distribution

pycares-4.4.0.tar.gz (821.6 kB view hashes)

Uploaded source

Built Distributions

pycares-4.4.0-cp312-cp312-win_amd64.whl (76.3 kB view hashes)

Uploaded cp312

pycares-4.4.0-cp312-cp312-win32.whl (61.5 kB view hashes)

Uploaded cp312

pycares-4.4.0-cp311-cp311-win_amd64.whl (76.3 kB view hashes)

Uploaded cp311

pycares-4.4.0-cp311-cp311-win32.whl (61.5 kB view hashes)

Uploaded cp311

pycares-4.4.0-cp310-cp310-win_amd64.whl (76.3 kB view hashes)

Uploaded cp310

pycares-4.4.0-cp310-cp310-win32.whl (61.5 kB view hashes)

Uploaded cp310

pycares-4.4.0-cp39-cp39-win_amd64.whl (76.3 kB view hashes)

Uploaded cp39

pycares-4.4.0-cp39-cp39-win32.whl (61.5 kB view hashes)

Uploaded cp39

pycares-4.4.0-cp38-cp38-win_amd64.whl (76.3 kB view hashes)

Uploaded cp38

pycares-4.4.0-cp38-cp38-win32.whl (61.5 kB view hashes)

Uploaded cp38

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page