pycookiecheat

pycookiecheat

Borrow cookies from your browser's authenticated session for use in Python scripts.

• Free software: MIT
• Documentation

Installation

NB: Use pip and python instead of pip3 and python3 if you're still on Python 2 and using pycookiecheat < v0.4.0. pycookiecheat >= v0.4.0 requires Python 3 and in general will aim to support python versions that are stable and not yet end-of-life: https://devguide.python.org/versions.

• python3 -m pip install pycookiecheat

Installation notes regarding alternative keyrings on Linux

See #12. Chrome is now using a few different keyrings to store your Chrome Safe Storage password, instead of a hard-coded password. Pycookiecheat doesn't work with most of these so far, and to be honest my enthusiasm for adding support for ones I don't use is limited. However, users have contributed code that seems to work with some of the recent Ubuntu desktops. To get it working, you may have to sudo apt-get install libsecret-1-dev python-gi python3-gi, and if you're installing into a virtualenv (highly recommended), you need to use the --system-site-packages flag to get access to the necessary libraries.

Alternatively, some users have suggested running Chrome with the --password-store=basic or --use-mock-keychain flags.

Development Setup

• git clone https://github.com/n8henrie/pycookiecheat.git
• cd pycookiecheat
• python3 -m venv .venv
• ./.venv/bin/python -m pip install -e .[dev]

Usage

As a Command-Line Tool

After installation, the CLI tool can be run as a python module python -m or with a standalone console script:

$ python -m pycookiecheat --help
usage: pycookiecheat [-h] [-b BROWSER] [-o OUTPUT_FILE] [-v] [-c COOKIE_FILE]
                     [-V]
                     url

Copy cookies from Chrome or Firefox and output as json

positional arguments:
  url

options:
  -h, --help            show this help message and exit
  -b BROWSER, --browser BROWSER
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        Output to this file in netscape cookie file format
  -v, --verbose         Increase logging verbosity (may repeat), default is
                        `logging.ERROR`
  -c COOKIE_FILE, --cookie-file COOKIE_FILE
                        Cookie file
  -V, --version         show program's version number and exit

By default it prints the cookies to stdout as JSON but can also output a file in Netscape Cookie File Format.

As a Python Library

from pycookiecheat import BrowserType, get_cookies
import requests

url = 'https://n8henrie.com'

# Uses Chrome's default cookies filepath by default
cookies = get_cookies(url)
r = requests.get(url, cookies=cookies)

# Using an alternate browser
cookies = get_cookies(url, browser=BrowserType.CHROMIUM)

Use the cookie_file keyword-argument to specify a different path to the file containing your cookies: get_cookies(url, cookie_file='/abspath/to/cookies')

You may be able to retrieve cookies for alternative Chromium-based browsers by manually specifying something like "/home/username/.config/BrowserName/Default/Cookies" as your cookie_file.

Features

• Returns decrypted cookies from Google Chrome, Brave, or Slack, on MacOS or Linux.
• Optionally outputs cookies to file (thanks to Muntashir Al-Islam!)

FAQ / Troubleshooting

How about Windows?

I don't use Windows or have a PC, so I won't be adding support myself. Feel free to make a PR :)

I get an installation error with the cryptography module on OS X

(pycookiecheat <v0.4.0)

If you're getting this error and using Homebrew, then you need to follow the instructions for Building cryptography on OS X and export LDFLAGS="-L$(brew --prefix openssl)/lib" CFLAGS="-I$(brew --prefix openssl)/include" and try again.

I get an installation error with the cryptography module on Linux

Please check the official cryptography docs. On some systems (e.g. Ubuntu), you may need to do something like sudo apt-get install build-essential libssl-dev libffi-dev python-dev prior to installing with pip.

How can I use pycookiecheat on KDE-based Linux distros?

On KDE, Chrome defaults to using KDE's own keyring, KWallet. For pycookiecheat to support KWallet the dbus-python package must be installed.

How do I install the (unreleased) master branch with pip?

• python -m pip install git+https://github.com/n8henrie/pycookiecheat@master

Buy Me a Coffee

☕️

Changelog

v0.8.0 :: 20241102

Breaking Changes

• url is now a positional argument (no longer requires -u)
• Browser type must be passed as a variant of the BrowserType enum; string is no longer supported
• Now requires python >= 3.9

CLI Enhancements

• Assume https:// if the scheme is not specified
• Add --version flag (thanks @samiam)
• Add -c flag to specify custom path to cookie file (thanks @samiam)
• Convert the browser argument into a BrowserType at parse time

Fixes / Other

• Fix new path to Firefox profile on MacOS (thanks @MattMuffin)
• Support Chrome's new v24 cookies (thanks @chrisgavin)
• Add new top-level get_cookies function that can be used for all supported browsers
  • No longer need to use separate chrome_cookies or firefox_cookies functions, but will leave these around for backwards compatibility
• Use ruff instead of hodgepodge of flake8 / pycodestyle / black and others

v0.7.0 :: 20240105

• Now requires python >= 3.8
  • 3.7 is now EoL: https://devguide.python.org/versions/
  • pycookiecheat seems to build and run on 3.7, but several test dependencies require versions that are either incompatible with 3.12 or 3.7
• Add BrowserType enum
  • Instead of passing a string (e.g. "chrome"), please import and use a BrowserType (e.g. BrowserType.CHROME)
  • Add deprecation warning for passing strings
• Added a nix flake to facilitate testing multiple python versions
• Add basic logging
• Add CLI tool
• Add as_cookies parameter to allow returning list[Cookie] instead of dict (without breaking backward compatibility)
• Loosen dependency constrains, which should make usage as a library easier

v0.6.0 :: 20230324

• Add firefox support, thanks to @grandchild
  • Also would like to welcome @grandchild as a new member of the pycookiecheat team!

v0.5.0 :: 20230324

• Add support for Brave thanks to @chrisgavin!
• Add support for Slack thanks to @hraftery!
• Migrate config to pyproject.toml alone
• Minor cleanup to codebase and tests

v0.4.7 :: 20210826

• No noteworthy API changes, hence the bugfix version bump, but some major infrastructure and testing updates:
  • Now uses GitHub Actions instead of Travis
  • Now uses Playwright for testing, to actually open a Chromium instance and use a real Cookies database
  • PEP517
  • black
• Now requires python >= 3.7
  • This is largely due to requiremets of Playwright: https://pypi.org/project/playwright/, which is only a test dependency
  • Because I can't test with <=3.6, I'm not listing it as compatible, though it probably will still work
• Migrate to pyproject.toml

v0.4.6 :: 2019111

• Try to open Chrome database in read-only mode to avoid db locked errors (#29)

v0.4.5 :: 20191007

• db6ac6d Go back to using cryptography due to https://www.cvedetails.com/cve/CVE-2013-7459/
• c70ad51 Allow users to override password (thanks @alairock)

v0.4.4 :: 20180706

• Optionally outputs cookies to a file compatible with cURL (thanks to Muntashir Al-Islam!)

v0.4.3 :: 20170627

• Consistently use Chrome as default across platforms, allow user to specify Chromium as desired (thanks @jtbraun)

v0.4.0 :: 20170504

• Remove compatibility for Python <3.5
• Add type hints
• Refactor for smaller functions
• Expand docstrings
• Revert from cryptography back to PyCrypto and hashlib for easier installation.

v0.3.4 :: 20170414

• Add support for new Ubuntu keyring / libsecret
  • See https://github.com/n8henrie/pycookiecheat/issues/12 for details
  • Many thanks to @stat1c1c3au and @trideceth12 for contributions

0.3.0

• Use cryptography instead of pycrypto (thanks to Taik!)
  • Seems to be significantly faster
  • Works with PyPy >= 2.6.0 (no support for PyPy3 yet)

0.2.0

• Fix domain and subdomain matching
• Make SQL query more secure by avoiding string formatting
• Many thanks to Brandon Rhodes for 24c4234 !

0.1.10

• Read version to separate file so it can be imported in setup.py
• Bugfix for python2 on linux

0.1.9

• Bugfix for python2 on linux

0.1.8

• Python2 support (thanks dani14-96)

0.1.7

• Configurable cookies file (thanks ankostis)

0.1.6

• OSError instead of Exception for wrong OS.
• Moved testing requirements to tox and travis-ci files.

0.1.5

• Updated to work better with PyPI's lack of markdown support
• Working on tox and travis-ci integration
• Added a few basic tests that should pass if one has Chrome installed and has visited my site (n8henrie.com)
• Added sys.exit(0) if cookie_file not found so tests pass on travis-ci.

0.1.0 (2015-02-25)

• First release on PyPI.

Prior changelog from Gist

• 20150221 v2.0.1: Now should find cookies for base domain and all subs.
• 20140518 v2.0: Now works with Chrome's new encrypted cookies.