feat!: replace requests with httpcloak for TLS fingerprinting (#2363)

[iiviie]

Summary

Replaces the requests library with httpcloak to bypass Instagram's TLS fingerprinting bot detection, fixing login and API blocking issues.
Closes #2363

Problem

Instagram uses JA3/JA4 TLS fingerprinting to detect and block automated requests. Python's requests library has a distinct fingerprint that Instagram easily identifies and blocks, causing login failures and "challenge required" errors.

Solution

Integrated HTTPCloak library which mimics real browser TLS fingerprints:

• Private API: ios-chrome-143 preset (mobile Instagram app)
• Public API: safari-18 preset (web browser)
• Uses tls_only=True mode to maintain custom User-Agent while keeping browser TLS fingerprint
  Major File Changes

Core Integration

pyproject.toml

• Version bump: 2.x.x → 3.0.0
• Dependency: requests==2.32.5 → httpcloak>=1.0.0
instagrapi/__init__.py
• Import change: requests → httpcloak
• Updated set_proxy(): Now calls session.set_proxy() method instead of setting proxies dict
  instagrapi/mixins/private.py
• Replaced requests.Session() with httpcloak.Session(preset="ios-chrome-143", tls_only=True)
• Removed HTTPAdapter and Retry strategy (httpcloak handles internally)
• Added get_header_value() helper for httpcloak's list-style headers
• Added None value filtering for headers before sending
  instagrapi/mixins/public.py
• Replaced requests.Session() with httpcloak.Session(preset="safari-18", tls_only=True)
• Removed HTTPAdapter and Retry strategy
• Updated request methods to use httpcloak session
  instagrapi/mixins/auth.py
• Updated cookie_dict property: cookies.get_dict() → cookies (already a dict)
• Updated init(): Use set_cookie() method instead of cookies.update()
• Updated session save/restore: Now saves httpcloak_session_data via marshal()/unmarshal()
• Updated inject_sessionid_to_public(): Use set_cookie() method
  instagrapi/mixins/password.py
• Added get_header_value() import and usage for header handling

Download Methods

instagrapi/mixins/photo.py, video.py, track.py

• Changed from standalone requests.get() to self.private.get() for consistent fingerprinting
• Updated download method: response.raw → response.iter_content(chunk_size=8192)
instagrapi/image_util.py
• External image downloads now use httpcloak.Session(preset="safari-18", tls_only=True)

Proxy/Cookie Handling

instagrapi/mixins/account.py, challenge.py

• Updated proxy access: session.proxies → session.get_proxy() with dict conversion
  Tests
  tests.py
• Line 11: Import change requests → httpcloak
• Line 126-131: Updated to use httpcloak.Session().get()
• Line 371: Fixed HTTPCloak Response compatibility (no .request attribute)

Breaking Changes

For advanced users only (public API unchanged):

Operation	v2.x (requests)	v3.x (httpcloak)
Get cookies	client.private.cookies.get_dict()	client.private.cookies
Set cookie	client.private.cookies.set("name", "val")	client.private.set_cookie("name", "val")
Clear cookies	client.private.cookies.clear()	client.private.clear_cookies()
Get proxy	client.private.proxies.get("https")	client.private.get_proxy()

Testing

Comprehensive test suite created and verified locally:

• Basic client instantiation with httpcloak sessions
• Cookie management (set, get, clear operations)
• Session persistence (save/restore with TLS state)
• Proxy handling (set_proxy/get_proxy methods)
• Real account login with TLS fingerprinting
• API calls (user_info, username lookup, timeline feed)
• Session save/restore after login
• Sessionid injection to public session
• HTTPCloak preset verification
  All core functionality verified working with no Instagram blocks detected.
  Documentation
• Updated README.md with HTTPCloak integration section
• Added docs/httpcloak.md - User guide, migration instructions, and troubleshooting

Migration

End users: No code changes required! Just upgrade:
pip install instagrapi --upgrade
Your existing code works as-is

Advanced users: See docs/httpcloak.md (docs/httpcloak.md) for session object changes.

Tested Presets

Preset	Status	Notes
ios-chrome-143	Works	Used for private API
ios-safari-17	Works	Alternative mobile
safari-18	Works	Used for public API
android-chrome-143	Blocked	Instagram detects
chrome-143	Blocked	Instagram detects

[ishiadv]

I have tested this httpcloak version, but it didn't work in my environment which old version worked.
Finished with the message.
instagrapi.exceptions.ClientBadRequestError: HTTP 400: Bad Request.

[iiviie]

@ishiadv hey yeah i encountered the same issue today, changing the Instagram outdated version 269.0.0.18.75 (OnePlus 6T) to 358.0.0.47.96 (Pixel 6 Pro) at libs/instagrapi/instagrapi/mixins/auth.py seemed to fix the issue

[ishiadv]

@iiviie
Isn't the httpcloak preset iOS...?
Does this really work by changing to Pixel 6 Pro?

[iiviie]

@ishiadv yup the httpcloak preset is ios, but i tried the android and chrome presets and they didnt seem to work, also as far as i know instagrapi overrides the agent anyways. But httpcloak alteast hides the TLS signature.
I've been using this config for over a week, haven't been flagged as bot yet

[favorPotato]

Good work, I did something similar too.
I analyzed the Instagram apk file and found that it downgrades to use okhttp.
So I created a combination based on rnet + okhttp.
I haven't uploaded the code yet (no time to test it), perhaps we could exchange ideas with each other.

[zekhoi]

got an issue when using it on my vps when fetching post comments, it says browser not supported