A Python library for automating interaction with websites.
Clone or download
hemberger and moy CONTRIBUTING.rst: Update release instructions
Add extra detail about how to specify version numbers and about
creating the release branch.
Latest commit 5926d0e Sep 12, 2018


MechanicalSoup. A Python library for automating website interaction.

Home page



A Python library for automating interaction with websites. MechanicalSoup automatically stores and sends cookies, follows redirects, and can follow links and submit forms. It doesn't do JavaScript.

MechanicalSoup was created by M Hickford, who was a fond user of the Mechanize library. Unfortunately, Mechanize is incompatible with Python 3 and its development stalled for several years. MechanicalSoup provides a similar API, built on Python giants Requests (for HTTP sessions) and BeautifulSoup (for document navigation). Since 2017 it is a project actively maintained by a small team including @hemberger and @moy.

Gitter Chat


Latest Version Supported Versions

PyPy and PyPy3 are also supported (and tested against).

Download and install the latest released version from PyPI:

pip install MechanicalSoup

Download and install the development version from GitHub:

pip install git+https://github.com/MechanicalSoup/MechanicalSoup

Installing from source (installs the version in the current working directory):

python setup.py install

(In all cases, add --user to the install command to install in the current user's home directory.)


The full documentation is available on https://mechanicalsoup.readthedocs.io/. You may want to jump directly to the automatically generated API documentation.


From examples/expl_duck_duck_go.py, code to get the results from a DuckDuckGo search:

"""Example usage of MechanicalSoup to get the results from

import mechanicalsoup

# Connect to duckduckgo
browser = mechanicalsoup.StatefulBrowser()

# Fill-in the search form
browser["q"] = "MechanicalSoup"

# Display the results
for link in browser.get_current_page().select('a.result__a'):
    print(link.text, '->', link.attrs['href'])

More examples are available in examples/.

For an example with a more complex form (checkboxes, radio buttons and textareas), read tests/test_browser.py and tests/test_form.py.


Build Status Coverage Status Requirements Status Documentation Status CII Best Practices LGTM Alerts LGTM Grade

Instructions for building, testing and contributing to MechanicalSoup: see CONTRIBUTING.rst.

Common problems

Read the FAQ.