Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If your traceback ends inside wkhtmltopdf/__init__.py at from main import WKhtmlToPdf, wkhtmltopdf, the likely problem is the old Python wrapper’s import layout—not a missing wkhtmltopdf command-line program. First confirm which Python interpreter is running your app and which package is installed in that interpreter. The legacy PyPI package is version 0.2, uploaded in 2011; reinstalling it is unlikely to make that old wrapper compatible with a modern Python environment.
What this error means
Python raises ImportError: No module named 'main' (or, in newer Python versions, ModuleNotFoundError: No module named 'main') when an import cannot be resolved. In the reported wkhtmltopdf case, the traceback points to the package initializer attempting an unqualified import: from main import WKhtmlToPdf, wkhtmltopdf. That is a strong clue that the installed wrapper expects an older package layout or import behavior.
This diagnosis is specific to that traceback. The same error text can arise from unrelated packages, local files, or environment problems. Read the full traceback before changing dependencies. If the failing line is in your own application rather than inside wkhtmltopdf, investigate that import separately.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteIdentify the Python environment and installed package
Run these commands with the same Python executable that starts your application:
#1 Best Overall
python -c "import sys; print(sys.executable)"
python -m pip show wkhtmltopdfThe first command prints the interpreter path. The second asks that interpreter’s pip for the package metadata. If you launch the app with python3, a virtual-environment path, or a specific executable, use that same command in both checks—for example, python3 -m pip show wkhtmltopdf. A plain pip show may refer to a different Python installation.
Check the reported package version and location against the file named in the traceback. Also inspect the project’s dependency file and deployment configuration: the package in a developer shell may not be the one imported by a service, notebook, container, or virtual environment.
Choose a repair route
Replace the old qoda wrapper if the application can change
The original qoda python-wkhtmltopdf project was archived on 2020-03-11; its README says “NO LONGER MAINTAINED.” PyPI’s wkhtmltopdf record lists version 0.2, with a source distribution uploaded on 2011-07-21. Treat it as a legacy dependency rather than assuming a reinstall will solve a Python 3 import error.
Before removing or replacing it, search the application for imports and calls that depend on its API. A package with a similar name may use different import names, functions, configuration, or operating-system support. Update the application and its dependency declaration together, then test in the same environment used in deployment.
Consider py3-wkhtmltopdf only if its limits fit
PyPI documents py3-wkhtmltopdf as a Python 3 fork of the unmaintained qoda project. Its listed release is 0.4.1, uploaded on 2020-11-28, and its status is Beta. The project documentation says Windows is unsupported. Those facts make it a possible route for a compatible non-Windows project, not a guaranteed or broadly current fix.
Check the fork’s current package description and installation instructions before adopting it. Confirm that its import API matches what your code needs, that your operating system is supported, and that the age and Beta classification are acceptable for your maintenance requirements. Do not assume that installing the fork under a related distribution name preserves every import or behavior of the older package.
Use pdfkit if a wrapper around the executable meets your needs
pdfkit is a Python wrapper for the separate wkhtmltopdf command-line utility. Installing the Python package alone does not provide that executable. Follow pdfkit’s package instructions for the wrapper and install the external executable using instructions appropriate to your operating system. The upstream wkhtmltopdf repository describes wkhtmltopdf as an HTML-to-PDF command-line renderer and wkhtmltoimage as its image-output counterpart; that upstream repository was archived on 2023-01-02.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Keep the two requirements distinct during diagnosis: Python must be able to import the wrapper, and the process must be able to find and run the renderer executable. Fixing one does not establish that the other is installed or configured.
Step-by-step troubleshooting
- Read the complete traceback. If it names the installed
wkhtmltopdf/__init__.pyand thefrom main import ...line, investigate the legacy wrapper. If a different file fails, follow that file and package instead. - Check the active interpreter. Run
python -c "import sys; print(sys.executable)"with the command used to start the application. - Inspect the package in that interpreter. Run
python -m pip show wkhtmltopdfand note its version and installation location. Substitute the exact Python command where necessary. - Check dependency declarations and expected imports. Find which code imports the package and what API it expects. Remove or replace the old dependency only after establishing what will replace those imports.
- Verify platform and maintenance fit. For
py3-wkhtmltopdf, account for the Beta status, 2020 release, and documented exclusion of Windows. For any replacement, check its actual import API and platform instructions. - If using pdfkit, verify both components. Install the Python wrapper and the external
wkhtmltopdfexecutable, then ensure the application process can locate the executable. - Retest in the application environment. First test the intended Python import; then make a small HTML-to-PDF conversion. A successful import alone does not prove that rendering works.
How to compare replacement packages
Do not choose by package name alone. Compare the points that determine whether a candidate will work in your application:
- Python support: Is the package documented for the Python version your application runs?
- Operating system: Does it support the deployment platform? The cited
py3-wkhtmltopdfdocumentation excludes Windows. - Maintenance: What is the latest listed release and its date, and what status does the project publish? The cited fork is Beta with a 2020 release.
- API compatibility: Do its imports and functions match your existing application, or will you need code changes?
- Rendering dependency: Does it bundle a renderer, or does it require the separate
wkhtmltopdfexecutable? With pdfkit, the executable is a separate requirement.
These checks are more reliable than installing a similarly named Django integration or changing an import based on an isolated suggestion. Community answers to the original question mention django-wkhtmltopdf and wkhtmltopdf.main; those are setup-specific anecdotes, not universal fixes. If your application uses Django, verify the integration package actually installed and follow its documented imports.
Common causes and fixes
- The traceback fails in the old package initializer: Confirm the package version and location; assess replacing the legacy wrapper rather than repeatedly reinstalling the same version.
- Commands report different package states: You may be checking a different Python installation. Use
python -m pipwith the application’s interpreter. - The import works but PDF creation fails: The renderer executable may be absent or inaccessible. Check the executable installation and how the application locates it.
- A suggested package does not work on your platform: Check that package’s documented OS support before installing it; the cited Python 3 fork excludes Windows.
- A replacement installs but application imports break: The replacement may not expose the old package’s API. Update imports and calling code according to that package’s own documentation.
Or skip the browser setup
If what you need is a screenshot of a web page rather than a locally generated PDF, ScreenshotNeo is a screenshot API and MCP server for developers; it is not a replacement for a Python import or the wkhtmltopdf renderer. Its API can return a screenshot or PDF from a URL in one GET request. Example:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for parameters. Cookie banners, popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are not billed. An MCP server lets AI agents take screenshots, and the Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo free.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Practical verification after changing dependencies
Make the import check and the output check separate steps so you know which requirement remains unresolved. In a fresh process using the application’s interpreter, import the package and confirm that the import completes. Then render a minimal HTML document to a PDF using the wrapper’s documented API. If the import fails, the traceback identifies the Python package path to investigate. If import succeeds but rendering fails, check executable availability, configuration, and platform-specific installation requirements.
Record the dependency version and interpreter used in the test, and reproduce the check in the actual deployment environment. A local shell can succeed while a service account, container, or production virtual environment still has another package version or cannot access the renderer. Avoid changing several packages or import paths at once: isolate the failing layer, make one change, and rerun both checks.
Frequently Asked Questions
Is `wkhtmltopdf` the same thing as the Python package named `wkhtmltopdf`?
No. The package is a Python wrapper; the wkhtmltopdf project also provides a separate command-line renderer. Some wrappers require that executable to be installed independently.
Will installing `django-wkhtmltopdf` fix this error?
Not necessarily. It is relevant only when the application uses that Django integration and its documented API. A similar package name does not establish compatibility with the failing import.
Does this error prove that Python itself is broken?
No. In the cited traceback, the failing import is inside the wrapper package. Other tracebacks with the same message can have different causes, so use the named file and line to guide diagnosis.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
