# pycookiecheat
[](https://github.com/n8henrie/pycookiecheat/actions/workflows/python-package.yml)
Borrow cookies from your browser's authenticated session for use in Python
scripts.
- Free software: MIT
- [Documentation](https://n8henrie.com/2013/11/use-chromes-cookies-for-easier-downloading-with-python-requests/)
## 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](https://github.com/n8henrie/pycookiecheat/issues/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
1. `git clone https://github.com/n8henrie/pycookiecheat.git`
1. `cd pycookiecheat`
1. `python3 -m venv .venv`
1. `./.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:
```console
$ 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
```python
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](https://github.com/n8henrie/pycookiecheat/pull/11#issuecomment-221918807)
and using Homebrew, then you need to follow the instructions for [Building
cryptography on OS
X](https://cryptography.io/en/latest/installation/?highlight=cflags#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`](https://pypi.org/project/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
[☕️](https://n8henrie.com/donate)
# [Changelog](https://keepachangelog.com)
## 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`](https://cryptography.io/en/latest/) instead of
`pycrypto` (thanks to [Taik](https://github.com/Taik)!)
- Seems to be [significantly
faster](https://github.com/n8henrie/pycookiecheat/pull/11#issuecomment-221950400)
- 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](https://github.com/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](https://github.com/dani14-96))
## 0.1.7
- Configurable cookies file (thanks [ankostis](https://github.com/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.
Raw data
{
"_id": null,
"home_page": null,
"name": "pycookiecheat",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "pycookiecheat, chrome, chromium cookies, cookies, firefox",
"author": null,
"author_email": "Nathan Henrie <nate@n8henrie.com>",
"download_url": "https://files.pythonhosted.org/packages/d0/12/0518335164660fcd6aaeee74b7db2f255cf7d1941721c915473e6322cc1e/pycookiecheat-0.8.0.tar.gz",
"platform": null,
"description": "# pycookiecheat\n\n[](https://github.com/n8henrie/pycookiecheat/actions/workflows/python-package.yml)\n\nBorrow cookies from your browser's authenticated session for use in Python\nscripts.\n\n- Free software: MIT\n- [Documentation](https://n8henrie.com/2013/11/use-chromes-cookies-for-easier-downloading-with-python-requests/)\n\n## Installation\n\n**NB:** Use `pip` and `python` instead of `pip3` and `python3` if you're still\non Python 2 and using pycookiecheat < v0.4.0. pycookiecheat >= v0.4.0 requires\nPython 3 and in general will aim to support python versions that are stable and\nnot yet end-of-life: <https://devguide.python.org/versions>.\n\n- `python3 -m pip install pycookiecheat`\n\n### Installation notes regarding alternative keyrings on Linux\n\nSee [#12](https://github.com/n8henrie/pycookiecheat/issues/12). Chrome is now\nusing a few different keyrings to store your `Chrome Safe Storage` password,\ninstead of a hard-coded password. Pycookiecheat doesn't work with most of these\nso far, and to be honest my enthusiasm for adding support for ones I don't use\nis limited. However, users have contributed code that seems to work with some\nof the recent Ubuntu desktops. To get it working, you may have to `sudo apt-get\ninstall libsecret-1-dev python-gi python3-gi`, and if you're installing into a\nvirtualenv (highly recommended), you need to use the `--system-site-packages`\nflag to get access to the necessary libraries.\n\nAlternatively, some users have suggested running Chrome with the\n`--password-store=basic` or `--use-mock-keychain` flags.\n\n### Development Setup\n\n1. `git clone https://github.com/n8henrie/pycookiecheat.git`\n1. `cd pycookiecheat`\n1. `python3 -m venv .venv`\n1. `./.venv/bin/python -m pip install -e .[dev]`\n\n## Usage\n\n### As a Command-Line Tool\n\nAfter installation, the CLI tool can be run as a python module `python -m` or\nwith a standalone console script:\n\n```console\n$ python -m pycookiecheat --help\nusage: pycookiecheat [-h] [-b BROWSER] [-o OUTPUT_FILE] [-v] [-c COOKIE_FILE]\n [-V]\n url\n\nCopy cookies from Chrome or Firefox and output as json\n\npositional arguments:\n url\n\noptions:\n -h, --help show this help message and exit\n -b BROWSER, --browser BROWSER\n -o OUTPUT_FILE, --output-file OUTPUT_FILE\n Output to this file in netscape cookie file format\n -v, --verbose Increase logging verbosity (may repeat), default is\n `logging.ERROR`\n -c COOKIE_FILE, --cookie-file COOKIE_FILE\n Cookie file\n -V, --version show program's version number and exit\n\n```\n\nBy default it prints the cookies to stdout as JSON but can also output a file in\nNetscape Cookie File Format.\n\n### As a Python Library\n\n```python\nfrom pycookiecheat import BrowserType, get_cookies\nimport requests\n\nurl = 'https://n8henrie.com'\n\n# Uses Chrome's default cookies filepath by default\ncookies = get_cookies(url)\nr = requests.get(url, cookies=cookies)\n\n# Using an alternate browser\ncookies = get_cookies(url, browser=BrowserType.CHROMIUM)\n```\n\nUse the `cookie_file` keyword-argument to specify a different path to the file\ncontaining your cookies:\n`get_cookies(url, cookie_file='/abspath/to/cookies')`\n\nYou may be able to retrieve cookies for alternative Chromium-based browsers by\nmanually specifying something like\n`\"/home/username/.config/BrowserName/Default/Cookies\"` as your `cookie_file`.\n\n## Features\n\n- Returns decrypted cookies from Google Chrome, Brave, or Slack, on MacOS or\n Linux.\n- Optionally outputs cookies to file (thanks to Muntashir Al-Islam!)\n\n## FAQ / Troubleshooting\n\n### How about Windows?\n\nI don't use Windows or have a PC, so I won't be adding support myself. Feel\nfree to make a PR :)\n\n### I get an installation error with the `cryptography` module on OS X\n(pycookiecheat <v0.4.0)\n\nIf you're getting [this\nerror](https://github.com/n8henrie/pycookiecheat/pull/11#issuecomment-221918807)\nand using Homebrew, then you need to follow the instructions for [Building\ncryptography on OS\nX](https://cryptography.io/en/latest/installation/?highlight=cflags#building-cryptography-on-os-x)\nand `export LDFLAGS=\"-L$(brew --prefix openssl)/lib\" CFLAGS=\"-I$(brew --prefix\nopenssl)/include\"` and try again.\n\n### I get an installation error with the `cryptography` module on Linux\n\nPlease check the official cryptography docs. On some systems (e.g. Ubuntu), you\nmay need to do something like `sudo apt-get install build-essential libssl-dev\nlibffi-dev python-dev` prior to installing with `pip`.\n\n### How can I use pycookiecheat on KDE-based Linux distros?\n\nOn KDE, Chrome defaults to using KDE's own keyring, KWallet. For pycookiecheat to support KWallet the [`dbus-python`](https://pypi.org/project/dbus-python/) package must be installed.\n\n### How do I install the (unreleased) master branch with pip?\n\n- `python -m pip install git+https://github.com/n8henrie/pycookiecheat@master`\n\n## Buy Me a Coffee\n\n[\u2615\ufe0f](https://n8henrie.com/donate)\n\n# [Changelog](https://keepachangelog.com)\n\n## v0.8.0 :: 20241102\n\n### Breaking Changes\n\n- `url` is now a positional argument (no longer requires `-u`)\n- Browser type must be passed as a variant of the `BrowserType` enum; string\n is no longer supported\n- Now requires python >= 3.9\n\n### CLI Enhancements\n\n- Assume `https://` if the scheme is not specified\n- Add `--version` flag (thanks @samiam)\n- Add `-c` flag to specify custom path to cookie file (thanks @samiam)\n- Convert the `browser` argument into a `BrowserType` at parse time\n\n### Fixes / Other\n\n- Fix new path to Firefox profile on MacOS (thanks @MattMuffin)\n- Support Chrome's new v24 cookies (thanks @chrisgavin)\n- Add new top-level `get_cookies` function that can be used for all supported\n browsers\n - No longer need to use separate `chrome_cookies` or `firefox_cookies`\n functions, but will leave these around for backwards compatibility\n- Use `ruff` instead of hodgepodge of `flake8` / `pycodestyle` / `black` and\n others\n\n## v0.7.0 :: 20240105\n\n- Now requires python >= 3.8\n - 3.7 is now EoL: https://devguide.python.org/versions/\n - pycookiecheat seems to build and run on 3.7, but several test\n dependencies require versions that are either incompatible with 3.12 or\n 3.7\n- Add `BrowserType` enum\n - Instead of passing a string (e.g. \"chrome\"), please import and use a\n `BrowserType` (e.g. `BrowserType.CHROME`)\n - Add deprecation warning for passing strings\n- Added a nix flake to facilitate testing multiple python versions\n- Add basic logging\n- Add CLI tool\n- Add `as_cookies` parameter to allow returning `list[Cookie]` instead of\n `dict` (without breaking backward compatibility)\n- Loosen dependency constrains, which should make usage as a library easier\n\n## v0.6.0 :: 20230324\n\n- Add firefox support, thanks to @grandchild\n - Also would like to welcome @grandchild as a new member of the\n pycookiecheat team!\n\n## v0.5.0 :: 20230324\n\n- Add support for Brave thanks to @chrisgavin!\n- Add support for Slack thanks to @hraftery!\n- Migrate config to pyproject.toml alone\n- Minor cleanup to codebase and tests\n\n## v0.4.7 :: 20210826\n\n- No noteworthy API changes, hence the bugfix version bump, but some major\n infrastructure and testing updates:\n - Now uses GitHub Actions instead of Travis\n - Now uses Playwright for testing, to actually open a Chromium instance and\n use a real `Cookies` database\n - PEP517\n - black\n- Now requires python >= 3.7\n - This is largely due to requiremets of Playwright:\n https://pypi.org/project/playwright/, which is only a *test* dependency\n - Because I can't *test* with <=3.6, I'm not listing it as compatible,\n though it *probably* will still work\n- Migrate to pyproject.toml\n\n## v0.4.6 :: 2019111\n\n- Try to open Chrome database in read-only mode to avoid db locked errors (#29)\n\n## v0.4.5 :: 20191007\n\n- db6ac6d Go back to using cryptography due to\n https://www.cvedetails.com/cve/CVE-2013-7459/\n- c70ad51 Allow users to override password (thanks @alairock)\n\n## v0.4.4 :: 20180706\n\n- Optionally outputs cookies to a file compatible with cURL (thanks to\n Muntashir Al-Islam!)\n\n## v0.4.3 :: 20170627\n\n- Consistently use Chrome as default across platforms, allow user to specify\n Chromium as desired (thanks @jtbraun)\n\n## v0.4.0 :: 20170504\n\n- Remove compatibility for Python <3.5\n- Add type hints\n- Refactor for smaller functions\n- Expand docstrings\n- Revert from `cryptography` back to `PyCrypto` and `hashlib` for easier\n installation.\n\n## v0.3.4 :: 20170414\n\n- Add support for new Ubuntu keyring / libsecret\n - See <https://github.com/n8henrie/pycookiecheat/issues/12> for details\n - Many thanks to @stat1c1c3au and @trideceth12 for contributions\n\n## 0.3.0\n\n- Use [`cryptography`](https://cryptography.io/en/latest/) instead of\n `pycrypto` (thanks to [Taik](https://github.com/Taik)!)\n - Seems to be [significantly\n faster](https://github.com/n8henrie/pycookiecheat/pull/11#issuecomment-221950400)\n - Works with PyPy >= 2.6.0 (no support for PyPy3 yet)\n\n## 0.2.0\n\n- Fix domain and subdomain matching\n- Make SQL query more secure by avoiding string formatting\n- Many thanks to [Brandon Rhodes](https://github.com/brandon-rhodes) for 24c4234 !\n\n## 0.1.10\n\n- Read version to separate file so it can be imported in setup.py\n- Bugfix for python2 on linux\n\n## 0.1.9\n\n- Bugfix for python2 on linux\n\n## 0.1.8\n\n- Python2 support (thanks [dani14-96](https://github.com/dani14-96))\n\n## 0.1.7\n\n- Configurable cookies file (thanks [ankostis](https://github.com/ankostis))\n\n## 0.1.6\n\n- OSError instead of Exception for wrong OS.\n- Moved testing requirements to tox and travis-ci files.\n\n## 0.1.5\n\n- Updated to work better with PyPI's lack of markdown support\n- Working on tox and travis-ci integration\n- Added a few basic tests that should pass if one has Chrome installed and has visited my site (n8henrie.com)\n- Added sys.exit(0) if cookie_file not found so tests pass on travis-ci.\n\n## 0.1.0 (2015-02-25)\n\n- First release on PyPI.\n\n## Prior changelog from Gist\n\n- 20150221 v2.0.1: Now should find cookies for base domain and all subs.\n- 20140518 v2.0: Now works with Chrome's new encrypted cookies.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Borrow cookies from your browser's authenticated session for use in Python scripts.",
"version": "0.8.0",
"project_urls": {
"homepage": "https://github.com/n8henrie/pycookiecheat"
},
"split_keywords": [
"pycookiecheat",
" chrome",
" chromium cookies",
" cookies",
" firefox"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b574a2757821296327ffda8f2bf8e5ec5aaa0e90c87caf948044f179b6228dab",
"md5": "f8df7a7cb3fcaa310448a24133ff262a",
"sha256": "e8b76ee1e15236b184973b1f5814647d81805712949dd8adeba46f61ffe7f12c"
},
"downloads": -1,
"filename": "pycookiecheat-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f8df7a7cb3fcaa310448a24133ff262a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18643,
"upload_time": "2024-11-03T16:52:31",
"upload_time_iso_8601": "2024-11-03T16:52:31.747471Z",
"url": "https://files.pythonhosted.org/packages/b5/74/a2757821296327ffda8f2bf8e5ec5aaa0e90c87caf948044f179b6228dab/pycookiecheat-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d0120518335164660fcd6aaeee74b7db2f255cf7d1941721c915473e6322cc1e",
"md5": "7bf5bfb9f1804cd4994ef014025557fa",
"sha256": "77bddb394a009e42483ed3808381f46e5c27fe2973dbb7dddec57a0573faa238"
},
"downloads": -1,
"filename": "pycookiecheat-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "7bf5bfb9f1804cd4994ef014025557fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 31509,
"upload_time": "2024-11-03T16:52:33",
"upload_time_iso_8601": "2024-11-03T16:52:33.120097Z",
"url": "https://files.pythonhosted.org/packages/d0/12/0518335164660fcd6aaeee74b7db2f255cf7d1941721c915473e6322cc1e/pycookiecheat-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-03 16:52:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "n8henrie",
"github_project": "pycookiecheat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pycookiecheat"
}
JSON
