Registry / devops / py-solc-x

py-solc-x

JSON →
library2.0.5pypypi✓ verified 87d ago

py-solc-x is a Python wrapper and version management tool for the `solc` Solidity compiler. It simplifies the installation, management, and use of multiple `solc` versions, allowing developers to compile Solidity code directly from Python. The current version is 2.0.5, and it sees frequent minor updates for bug fixes and occasional feature releases.

pip install py-solc-x
INSTALL
IMPORT
SIG · PY-SOLC-X
P
py-solc-x
devopspythonv2.0.5
Install
2.2s avg
Import
688ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.0.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.728s · 22.1MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.2s · import 0.648s · 23MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

solcx
import solcx
Most functionality is accessed via the top-level `solcx` module.
compile_source
from solcx import compile_source
For direct compilation of Solidity source code.

This quickstart demonstrates how to install a specific `solc` version, set it as the active compiler, and then compile a simple Solidity contract source code using `py-solc-x`. It outputs the contract's ABI and bytecode.

import solcx import os solidity_code = ''' pragma solidity ^0.8.0; contract SimpleStorage { uint256 public storedData; constructor(uint256 initialData) { storedData = initialData; } function set(uint256 x) public { storedData = x; } function get() public view returns (uint25n) { return storedData; } } ''' # Ensure a solc version is installed # Using os.environ.get for an example, in real use specify a version like '0.8.10' target_version = os.environ.get('SOLC_VERSION', '0.8.10') if not solcx.get_installed_solc_versions(): print(f"No solc versions found. Installing {target_version}...") solcx.install_solc(target_version) # Select the desired solc version. This is crucial. solcx.set_solc_version(target_version) print(f"Using solc version: {solcx.get_solc_version()}") # Compile the Solidity code compiled_sol = solcx.compile_source( solidity_code, output_values=['abi', 'bin'] ) # Extract contract data contract_name = '<stdin>:SimpleStorage' contract_abi = compiled_sol[contract_name]['abi'] contract_bytecode = compiled_sol[contract_name]['bin'] print("\n--- Compiled Contract ABI ---") print(contract_abi) print("\n--- Compiled Contract Bytecode ---") print(contract_bytecode[:60] + '...') # Print first 60 chars of bytecode for brevity
solc --version
Debug
Known issues
breakingVersion 2.0.0 introduced significant internal changes to version handling, now utilizing the `packaging.Version` library. Code that relied on string-based comparisons or custom parsing of `solc` versions might behave differently or break. Ensure your version strings are compatible.
fix
Review how `solc` versions are parsed and compared in your application. Ensure they are compatible with `packaging.Version`'s parsing logic. Direct usage of `solcx.set_solc_version` should still work with standard version strings, but be aware of stricter internal checks.
affects: >=2.0.0
gotchaStarting with v2.0.5, `solc` binaries are consistently fetched from `binaries.soliditylang.org`. Users operating in restrictive network environments or those expecting binaries from a different source (e.g., GitHub releases, if previously configured) might encounter download issues.
fix
Ensure network access to `binaries.soliditylang.org` is permitted. If manual binary management is required, consider using `solcx.set_solc_path()` after downloading the binary yourself.
affects: >=2.0.5
gotchaPrior to v2.0.1, the `select_pragma_version` method was not publicly exposed. If your application needs to programmatically determine and set the correct `solc` version based on a contract's `pragma solidity` statement, this functionality was more difficult to implement.
fix
Upgrade to `py-solc-x` v2.0.1 or newer to gain access to `solcx.select_pragma_version` for easier pragma-based version selection.
affects: <2.0.1
gotchaOlder versions of `py-solc-x` (specifically prior to v1.1.0) had issues correctly handling the ABI format for Solidity 0.8.0 and newer versions. This could lead to incorrect ABI output or compilation failures for modern contracts.
fix
Upgrade to `py-solc-x` v1.1.0 or newer when compiling Solidity contracts written for version 0.8.0 or later to ensure correct ABI generation.
affects: <1.1.0
Errors
Common errors & fixes
solcx.exceptions.SolcNotInstalled: Solc is not installed. Please install it with solcx.install_solc() or set your solc path with solcx.set_solc_path().
The `solc` compiler binary required for compilation is not found in the expected locations or has not been installed by `py-solc-x`.
fix
Call `solcx.install_solc('X.Y.Z')` to download and install a specific `solc` version, where 'X.Y.Z' is the desired version (e.g., '0.8.10'). Alternatively, if `solc` is already installed elsewhere, use `solcx.set_solc_path('/path/to/solc')`.
solcx.exceptions.SolcError: An error occurred during compilation. Command: ['/path/to/solc', '--abi', ...] Output: ... Error: Source file requires different compiler version (current compiler is ...).
The Solidity source code contains errors (syntax, missing imports, semantic issues) or the active `solc` compiler version does not satisfy the `pragma solidity` declaration in the contract.
fix
Inspect the full `Output:` and `Error:` messages from the `SolcError` for specific details from the `solc` compiler. Correct any Solidity syntax errors, ensure all imported files are accessible, and verify that the `solcx.set_solc_version()` call selects a `solc` compiler version that matches your contract's `pragma solidity`.
solcx.exceptions.VersionMismatchError: Pragma "^0.8.0" does not match current solc version "0.7.6"
The `pragma solidity` directive in your contract specifies a version range (e.g., `^0.8.0`) that is not satisfied by the `solc` version currently set via `solcx.set_solc_version()`.
fix
Ensure that the `solc` version you have selected with `solcx.set_solc_version()` (or that `py-solc-x` automatically selects) falls within the range specified by your contract's `pragma solidity`. You might need to `solcx.install_solc('X.Y.Z')` and then `solcx.set_solc_version('X.Y.Z')` to use a compatible compiler.
Upgrade
Version history
2.0.5latest on PyPI · released Dec 10, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
20 hits · last 30 days
node
18
Resources
py-solc-x — pip install py-solc-x · libregistry