Skip to main content

An easy-to-use and lightweight API wrapper for Censys APIs (

Project description

Censys Python Library

PyPI Python Version Read the Docs (version) GitHub Discussions PRs Welcome License

An easy-to-use and lightweight API wrapper for Censys APIs ( Python 3.8+ is currently supported. This library has been tested on Python 3.8 and 3.x (Currently version 3.10).

Notice: The Censys Search v1 endpoints are deprecated as of Nov. 30, 2021. Please begin using v2 endpoints to query hosts and certificates and check out our support center for resources.


Getting Started

The library can be installed using pip.

pip install censys

To upgraded using pip.

pip install --upgrade censys

Alternatively, you can install the library using poetry.

git clone
cd censys-python/
poetry install

Optionally, you can enable tab completion for the CLI by adding this line to your ~/.bashrc, ~/.zshrc, or equivalent.

Please note that autocomplete is supported for field names in the search command.

eval "$(register-python-argcomplete censys)"

To configure your search credentials run censys config or set both CENSYS_API_ID and CENSYS_API_SECRET environment variables.

$ censys config

Censys API ID: XXX
Censys API Secret: XXX
Do you want color output? [y/n]: y

Successfully authenticated for

If you have a Censys ASM account, you can configure your ASM credentials by running censys asm config or set both CENSYS_ASM_API_KEY environment variables.

$ censys asm config

Censys ASM API Key: XXX
Do you want color output? [y/n]: y

Successfully authenticated


The examples located in the examples/ directory are a great place to start. You can also find more examples in the usage documentation.


Read the Docs



All contributions (no matter how small) are always welcome. See Contributing to Censys Python


This project uses poetry for dependency management. Please ensure you have installed the latest version.

git clone
cd censys-python/
poetry install


# Run tests
poetry run pytest
# With coverage report
poetry run pytest --cov-report html


This software is licensed under Apache License, Version 2.0

  • Copyright (C) 2023 Censys, Inc.

Download files

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

Source Distribution

censys-2.2.9.tar.gz (58.8 kB view hashes)

Uploaded source

Built Distribution

censys-2.2.9-py3-none-any.whl (75.5 kB view hashes)

Uploaded py3

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