icp-py-core Release Update
After community discussion, the new Python SDK repository has been officially named icp-py-core to align with the style of icp-js-core and unify developer tooling across ecosystems.
The first release, v1.0.0, will soon be published on PyPI. Over time, the project will be restructured into a modular format (candid, identity, agent), mirroring the organization of icp-js-core for better maintainability and consistency.
Stay tuned for the PyPI release announcement! 
@C-B-Elite ,
I have a question about the two different approaches available:
The canister instance approach is very convenient and I typically prefer that, but I ran into some problems sometimes and had to fall back to the agent approach.
What approach do you recommend?
Will the canister instance capability be further maintained? I once tried to understand how it was created but it is very complicated…
Thank you for your question,
By the way, I’m currently in the process of reorganizing the ic-py project structure into the proper base framework for icp-py-core. This restructuring work will be completed within this week, after which I will publish icp-py-core to PyPI.
Regarding the Canister instance, I have one particular issue that I like to submit. What is the best place to do that?
Submit your issue here:
It’s best to include the relevant code snippet that demonstrates the problem.
once the new release is published on PyPi, please also provide a PR to GitHub - dfinity/awesome-internet-computer: A curated list of awesome projects and resources relating to the Internet Computer Protocol 
I think it would be reasonable to replace the old agent and give the original author some credit in the readme of your new repo 
While working on icp-py-core, I found that refactoring the original project structure has taken more time than I initially expected, which caused the release to be delayed. Based on the current progress, I should be able to complete the refactoring and publish icp-py-core this week.
I’ve also renamed some of the original ic-py API interfaces in icp-py-core to better align with icp-js-core and Rust’s agent-rs. This is to reduce the risk of major breaking changes to the interface in the future.
I took a short break last week (I probably should have posted this before taking the break). I’m now back from vacation and will be pushing forward with progress as quickly as possible.
Release Announcement: icp-py-core v1.0.0 — First Stable VersionRelease Date: 2025-10-20
Author: Elie Zhao
icp-py-coreis a modernized and actively maintained fork ofic-py, fully compatible with Internet Computer Boundary Node v3 endpoints and offering a more developer-friendly Python Agent API.
OverviewThis is the first stable release (v1.0.0) of icp-py-core.
It introduces a modular architecture, improved reliability, optional BLS certificate verification, and full API parity with the Rust/TypeScript IC Agents.
Highlights:
src/ with separate subpackages: agent / identity / candid / principal / certificate)icp_core/api/v3/canister/.../callAgent.update() and Agent.query() with auto Candid encodingblst (recommended for production)
Installationpip install icp-py-core
Requires Python 3.9+.
To enable certificate verification, follow theblstinstallation guide in the README.
Quick Start Examplefrom icp_core import Agent, Client, Identity, Types
iden = Identity() # or from private key: Identity(privkey="hex...")
client = Client("https://ic0.app")
agent = Agent(iden, client)
# Update: auto Candid encoding for non-bytes arguments
agent.update("wcrzb-2qaaa-aaaap-qhpgq-cai", "set", [{'type': Types.Nat, 'value': 2}],
verify_certificate=True)
# Query: auto-encodes empty args when None or []
res = agent.query("wcrzb-2qaaa-aaaap-qhpgq-cai", "get", None, return_type=[Types.Nat])
print(res)
Setting
verify_certificate=Trueperforms BLS verification on the response — recommended for production.
Key Improvementssrc/
├── icp_agent/ # Agent & HTTP client
├── icp_identity/ # Identity (ed25519, secp256k1)
├── icp_candid/ # Candid encoder/decoder & parser
├── icp_principal/ # Principal utilities (strict DER mode)
├── icp_certificate/ # Certificate verification (BLS12-381)
├── icp_core/ # Unified import facade
icp_corefrom icp_core import Agent, Client, Identity, Principal, Certificate, encode, decode, Types
Agent.update() and Agent.query() methods (aligned with Rust/TS IC Agents)Principal.self_authenticating() now accepts only DER format for stronger compliance and securitypoll() and poll_and_wait() now mirror Rust Agent semanticsantlr4-python3-runtime==4.9.3 to resolve ATN version mismatchpyproject.toml (replacing setup.py)MANIFEST.in (excludes .venv-test, tests, .git)httpx, cbor2, leb128, ecdsa, PyNaClblst (for certificate verification)
Migration from ic-pyfrom icp_core import Agent, Client, Identity, encode, decode, Types, Principal, Certificateicp_agent, icp_identity, icp_candid, icp_principal, icp_certificateupdate() and query() now automatically Candid-encode arguments (no manual encode() required)See MIGRATION.md in the repository for detailed mapping.
Stability and Securityverify_certificate=True)blst bindings
RoadmapCompleted:
Milestone 1 — v3 Endpoint Migration & Polling Stability Milestone 2 — BLS Certificate VerificationNext Steps:
Candid type-system enhancements
Dynamic routing between boundary nodes
ICRC helpers and token canister wrappersFull roadmap available in ROADMAP.md.
Links
AcknowledgmentsThanks to the DFINITY community, original ic-py contributors, and everyone supporting this ongoing project.
icp-py-core aims to provide a modern, secure, and Pythonic SDK for the Internet Computer.
Feedback, issues, and PRs are warmly welcome!
@C-B-Elite
I reported an issue related to Authenticated Query calls that are not working.
Also mentioning it here for visibility.
If everything in the PR looks good, the fix will be included in the next release. I’m currently working on some other features as well.
Thanks for your contribution!
Hey @C-B-Elite ,
I want to thank you again for taking up this project and shoutout to the first release.
We have successfully upgraded a part of our off-chain monitoring service for funnAI from using a wrapped dfx command via subprocess to using an Agent via icp-py-core. This is a django/celery based application, so having a maintained python agent was really important.
It interacts with some really complex interfaces (variants of records with complex opt fields) and it all works great.
Hi, thank you for submitting the two PRs, and thanks for your recognition and contributions to icp-py-core.
There are still a few issues in the detailed implementation of the PRs, and since my local changes have diverged quite a bit from the remote repository, I’ve decided to merge your PRs into the main repo first. I’ll further refine and optimize the modified parts afterward.
Thanks again for your contribution!
AnnouncingWe are pleased to announce the release of icp-py-core v2.0.0, a significant update that brings stronger default security and important reliability fixes for Python developers building on the ICP.
This release includes a breaking change, two critical bug fixes, and several improvements contributed by the community.
A special thanks to @icpp for reporting issues, proposing improvements, and contributing to this release.
Breaking Change: Certification Verification Enabled by DefaultStarting from v2.0.0 , response certification verification is now enabled by default for all query calls.
Previously, certification checks were disabled by default, which meant unverified responses could be consumed without warning. Enabling verification by default ensures that developers receive trusted, certified data unless they explicitly opt out.
If you need the previous behavior (e.g., testing or compatibility):
client = IcpClient(..., verify_certification=False)
Because this change may cause existing code to fail when interacting with canisters that do not provide certified responses, this update is released as a major version bump.
Bug FixesAn issue where Principal decoding failed due to a missing flag byte has been resolved.
This improvement aligns Principal parsing with expected IC specifications.
Thanks to @icpp for reporting the issue.
An issue causing authenticated query calls to fail unexpectedly has been fixed, restoring correct behavior for identity-based or certified queries.
This problem was also identified with the help of @icpp.
Installation & UpgradeUpgrade via PyPI:
pip install --upgrade icp-py-core
Or install explicitly:
pip install icp-py-core==2.0.0
PyPI: Client Challenge
Github: Release v2.0.0 · eliezhao/icp-py-core · GitHub
Community AcknowledgmentOnce again, thank you @icpp for identifying issues and contributing to the security and correctness of this release.
Community feedback has been essential in moving this library forward.
Feedback & ContributionsIf you encounter any issues or have feature requests, please feel free to open an issue or PR on GitHub.
thanks for the update! 
I just observed that v1.0.0 is still marked as latest on GitHub. you might want to tag v2.0.0 as latest 
Good catch! I’ve updated it. Thank you!
Update:
Based on feedback from icp-py-core users, I’m prioritizing improvements to the robustness and stability of the Candid parser, as well as enhancements to the Canister class implementation.
I’ve been working on fixing vulnerabilities in the current Candid parser, but the existing design is based on a rather fragile approach. Continuing to patch it may make future maintenance increasingly difficult. Because of this, I’m considering adopting a different technical solution. Over the coming days, I’ll be exploring whether this new approach can make the parser more reliable and structurally sound.
This work is expected to take about a week to complete.
Thank you for the focus on the Canister class.
A new and important release is coming very soon — featuring a solid and reliable Candid parser for icp-py-core.
icp-py-core v2.1.0 ReleasedI’m pleased to announce icp-py-core v2.1.0, a major release with performance improvements, new features, and comprehensive examples for Python developers building on the Internet Computer.
Most Important UpdateThe long-standing issue that has troubled developers - where Candid content could not be correctly read and Canister classes could not be properly created - has been completely resolved. The underlying Candid parsing modules have been completely rewritten using a more rigorous approach that fully complies with the Candid specification.
Quick Start
pip install icp-py-core
# or upgrade from v2.0.0:
pip install --upgrade icp-py-core
Performance Breakthrough: Rust-Based Candid ParserProblem Solved: The previous Python ANTLR4-based Candid parser was slow and memory-intensive, causing delays when parsing complex DID files.
Solution: Migrated to a Rust-based implementation using the candid-parser crate:
Multiple times faster parsing - Dramatically improved DID file parsing performance
Reduced memory usage - More efficient resource consumption
Faster startup - Quicker canister interface initialization
Pre-built binary wheels - No Rust compiler required for installation
Zero breaking changes - Full backward compatibility with v2.0.0
New Features & EnhancementsProblem Solved: Developers needed practical, working examples for common IC operations.
Solution: Added a comprehensive set of production-ready examples:
ledger_example.py - ICP transfers, balance queries, transaction history
governance_example.py - Neuron management, proposals, voting
cycles_wallet_example.py - Cycles transfers, wallet operations, canister creation
management_example.py - Canister lifecycle management
simple_counter_example.py - Basic query/update patterns with error handling
helpers.py - Common utility functions and formatted output helpers
All examples include proper error handling and can be used as templates for your projects.
Problem Solved: Limited governance functionality made it difficult to interact with NNS programmatically.
Solution: Expanded the Governance module from ~218 to 1510 lines with full NNS interface coverage:
Complete proposal creation and management
Full voting functionality with type-safe operations
Comprehensive neuron management and configuration
All governance operations now available via Python API
Problem Solved: Complex, hard-to-maintain codebase with unclear error messages.
Solutions:
New DIDLoader class - Cleaner API with better error messages, recursive type support, and complete service interface parsing
Canister module refactored - Reduced from 1322 to ~112 lines (90%+ reduction) while maintaining full backward compatibility
Better error handling and dynamic method binding
New comprehensive test files: test_did_loader_comprehensive.py, test_parser.py
Enhanced test_candid_comprehensive.py with 186 new lines
All 56 tests passing with ~7.3 seconds test duration
Fixes & ImprovementsProblem Solved: Users struggled with blst installation for certificate verification.
Solution: Added comprehensive installation guide (150+ lines) covering:
Prerequisites for macOS, Linux (Ubuntu/Debian, Fedora/RHEL), and Windows
Three installation methods: development, production, and virtual environment
Complete troubleshooting section
Installation verification examples
Fixed AccountIdentifier length validation
Fixed verify_certificate default to True (matching Agent.update() for security)
Fixed verify_certificate extraction from kwargs in Canister methods
Fixed pyproject.toml module-name matching wheel installation
What This Release Delivers Performance: Multiple times faster Candid parsing with Rust backend
Examples: Complete production-ready code library (6 examples)
Governance: Full NNS Governance interface implementation (1510 lines)
Code Quality: 90%+ reduction in Canister module complexity
Documentation: Comprehensive installation and usage guides
Reliability: All 56 tests passing, full backward compatibility
Technical Highlights:
Rust extension with PyO3 bindings (pre-built wheels, no Rust compiler needed)
Removed ~2000+ lines of legacy ANTLR code
Net: +1212 lines (41 files changed, +5951 added, -4739 deleted)
Migration from v2.0.0No breaking changes! v2.1.0 is fully backward compatible with v2.0.0. All existing code will continue to work without modification. The performance improvements and new features are additive.
ResourcesGitHub Releases: Releases · eliezhao/icp-py-core · GitHub
PyPI Package: icp-py-core · PyPI
GitHub Repository: GitHub - eliezhao/icp-py-core: Python Agent Library for the DFINITY Internet Computer
Full Changelog: icp-py-core/CHANGELOG.md at master · eliezhao/icp-py-core · GitHub
Examples: icp-py-core/examples at master · eliezhao/icp-py-core · GitHub
Thank YouThanks to the IC community and all contributors. We’re committed to maintaining a modern, performant Python SDK for the Internet Computer.