Install & Compatibility
Where this runs
tested against v4.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 2.714s · 67.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 7.7s · import 2.604s · 84MB
78MB installed
● package 78MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PyFunceble
✓ from PyFunceble import PyFunceble
✗ import pyfunceble
The primary programmatic entry point is the PyFunceble class itself, not the package as a whole.
Engine
✓ from PyFunceble import Engine
For more advanced control or integration with PyFunceble's core engine logic.
This quickstart demonstrates how to programmatically use PyFunceble to check the status of domains. It initializes the PyFunceble engine, tests a single domain, and prints key results. A temporary directory is used for output files to keep your system clean, and logging is suppressed for a concise output.
import tempfile
import shutil
from PyFunceble import PyFunceble
# Create a temporary directory for PyFunceble's output (logs, databases)
output_dir = tempfile.mkdtemp()
try:
print(f"PyFunceble output will be stored in: {output_dir}")
# Initialize PyFunceble. Pass output_dir to control where files are created.
# For a fully quiet operation, you can configure logging separately.
funceble = PyFunceble(output_dir=output_dir,
log_level='CRITICAL',
autodisconnect=True)
# Test a single domain
domain_to_test = "google.com"
print(f"\nTesting '{domain_to_test}'...")
results = funceble.test_single(domain_to_test)
print(f"Results for {domain_to_test}: Status = {results.get('status', 'N/A')}, ")
print(f" Expiration = {results.get('expiration_date', 'N/A')}, ")
print(f" HTTP Status = {results.get('http_status_code', 'N/A')}")
# Test a known non-existent domain (for demonstration)
non_existent_domain = "thisdomainreallyshouldntexist.xyz"
print(f"\nTesting '{non_existent_domain}'...")
results_non_existent = funceble.test_single(non_existent_domain)
print(f"Results for {non_existent_domain}: Status = {results_non_existent.get('status', 'N/A')}")
finally:
# Clean up the temporary directory after use
print(f"\nCleaning up temporary output directory: {output_dir}")
shutil.rmtree(output_dir)
pyfunceble --version
Debug
Known issues
breakingVersion 4.0.0 introduced a significant rewrite of the internal data work and a reinforcement of the Python module. Users upgrading from the 3.x series should expect breaking changes, especially if relying on deep internal interactions.fixReview the official PyFunceble v4 documentation and migration guides. Update any code interacting directly with PyFunceble's internal structures or previously deprecated APIs.
affects: >=4.0.0 (from 3.x)
gotchaPrior to v4.3.0, there were issues using MariaDB or PostgreSQL databases in 'single mode' (without a file-based input). This could lead to errors or unexpected behavior when trying to persist or retrieve data.fixUpgrade to PyFunceble v4.3.0 or newer. Ensure your database configuration is correct and accessible.
affects: <4.3.0
gotchaDevelopers interacting with PyFunceble's database layer should be aware that the way PyFunceble works and interacts with SQLAlchemy 2.0 Declarative Mapping was improved in v4.3.1. This might affect custom integrations or extensions.fixConsult the PyFunceble GitHub repository for changes related to SQLAlchemy 2.0 interaction. Ensure your code aligns with the updated declarative mapping patterns if you're extending PyFunceble's ORM.
affects: >=4.3.1
gotchaEarlier versions (prior to v4.2.27) experienced unstable results when testing against HTTP status codes, leading to potentially inaccurate availability assessments.fixUpgrade to PyFunceble v4.2.27 or newer to benefit from improved stability and accuracy in HTTP status code checks.
affects: <4.2.27
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'PyFunceble'
The pyfunceble-dev package is not installed in your current Python environment, or the environment is not active.
fixRun `pip install pyfunceble-dev` to install the package. If using a virtual environment, ensure it's activated.
TypeError: PyFunceble.__init__() got an unexpected keyword argument 'config_file'
In PyFunceble v4.x, the 'config_file' parameter for initialization has been removed. Configuration is now primarily handled through constructor arguments or the internal configuration module.
fixRemove the `config_file` argument from the PyFunceble constructor. Instead, pass configuration options directly as keyword arguments (e.g., `PyFunceble(output_dir='...', log_level='...')`) or manage configuration via `PyFunceble.configure()`.
PyFunceble.exceptions.ConnectionError: The following DNS server(s) failed to respond: [...]
PyFunceble could not reach any configured or default DNS servers. This can be due to network issues, misconfigured DNS settings on the system, or firewalls blocking DNS traffic.
fixCheck your system's network connectivity and DNS server configuration. Ensure ports 53 (UDP/TCP) are not blocked. PyFunceble v4.2.0 and above provide default Quad9 DNS servers if none are found, so upgrading may help in some cases.
Upgrade
Version history
4.4.1latest on PyPI · released Jan 24, 2026
Audit
Dependencies
SQLAlchemyrequiredUsed for internal database management and persistence.
cryptographyrequiredRequired for secure operations; minimum version updates often address vulnerabilities.