solc-select: two commands for juggling Solidity compiler versions

Two executables, and the second one shadows your solc

solc-select is a tool to quickly switch between Solidity compiler versions, and it is split into two command line utilities.

`solc-select` manages installing and setting different solc compiler versions. `solc` is a wrapper around solc which picks the right version according to what was set via solc-select. That wrapper is the part people should understand before installing anything, because it means the `solc` on your PATH is no longer the one your package manager gave you.

The binaries themselves come from https://binaries.soliditylang.org/, which the documentation describes as containing official artifacts for many historical and modern solc versions for Linux and macOS. The versioned binaries are stored in `~/.solc-select/artifacts/`.

The distribution channel is the Python ecosystem. The project publishes two console scripts, `solc-select` and `solc`, both pointing into the same module, `solc_select.__main__`. The package version is 1.2.0, requires Python 3.10 or newer, and its runtime dependencies are `pycryptodome`, `packaging` and `requests`. The pycryptodome dependency is there for the signature checking that the official binary list supports, and `packaging` is used for version comparison.

The metadata is written by Trail of Bits, with the maintainer contact being [email protected], and the classifiers mark the project as Production/Stable under the AGPL-3.0 licence.

Installing it takes one command, and puts solc on your PATH

There are two documented installation routes, one through uv and one through pip:

uv tool install solc-select

pip3 install solc-select

The uv route is the cleaner one for a tool like this, because `uv tool install` puts the command in an isolated environment rather than in your project virtualenv, which avoids the tool's dependencies ending up in a requirements file for a Solidity project that has nothing to do with Python.

The development setup in the Makefile follows the classic pattern of a virtual environment and an editable install:

make dev

which creates a venv named `env`, activates it and runs `pip install -e .`.

What you should see after installation is that both commands resolve, and that `solc --version` reports a compiler. The documentation is explicit that solc-select re-installs solc binaries for your operating system and acts as a wrapper for solc.

That last point is the one to internalise before you install it. The documentation also states that solc-select is intended to work with custom binaries, which means Solidity installed through other means, such as `brew install solidity`, will not work with it. If you have a system solc, that is the thing to remove first.

The global version, the environment variable, and the flag that installs on demand

Three mechanisms decide which compiler runs, and they are worth understanding in order because they interact.

The global version is what solc-select stores as the current selection, and the documentation says it is automatically set to the latest version. The quick start shows the basic cycle:

solc-select use 0.8.19 --always-install

solc --version

The `SOLC_VERSION` environment variable overrides the global version for a single invocation, which is what you want in CI or in a script that builds against a specific release:

$ SOLC_VERSION=0.5.2 solc --version
solc, the solidity compiler commandline interface
Version: 0.5.2+commit.1df8f40c.Linux.g++

The third mechanism is the flag. By default solc-select halts if you ask for a version you do not have installed already, and `--always-install` bypasses that:

$ solc-select use 0.8.1 --always-install
Installing '0.8.1'...
Version '0.8.1' installed.

The command set is small: `solc-select install` lists all available versions, `solc-select install 0.8.19` installs one, `solc-select use 0.8.19` switches to an installed one, `solc-select versions` lists what is installed, and `solc-select use 0.8.19 --always-install` does both at once. There is no uninstall command in the documented list, which means the artifacts directory grows unless you clear it by hand.

Architecture support has a hard floor that depends on your machine

This is where the practical friction lives, and it is worth reading carefully before you promise a team that a specific compiler version will work on their laptops.

On macOS ARM, solc-select provides native ARM64 support for versions 0.8.5 to 0.8.23, and universal binary support for 0.8.24 and later. For versions older than 0.8.5, Rosetta is required. The FAQ explains the failure you get when that is missing, which surfaces as an OSError with errno 86, Bad CPU type in executable, or as a message saying the macOS binaries are Intel-only.

There is a documented check for whether Rosetta is present:

pgrep -q oahd && echo Rosetta is installed || echo Rosetta is NOT installed

and a documented install command:

/usr/sbin/softwareupdate --install-rosetta --agree-to-license

On Linux ARM the situation is different and less friendly. Native ARM64 support exists for 0.8.31 and newer. For older versions QEMU is required, specifically `qemu-x86_64`, and the documentation adds that a libc binary, for example from the `libc6-amd64-cross` package, plus an adequate `QEMU_LD_PREFIX` environment variable such as `QEMU_LD_PREFIX=/usr/x86_64-linux-gnu` might be necessary to execute solc binaries that are not built statically.

The pattern to notice is that the ARM story gets worse the older the compiler you want. If your build matrix includes a legacy Solidity version, which is common in projects supporting older on-chain contracts, that combination is where you will spend the time.

The most common failure is a second solc on the machine

Three of the four documented known issues are the same issue wearing different clothes, and it is worth internalising before debugging anything else.

The symptom is that `solc-select use <version>` succeeds, and then `solc --version` reports something older. The cause is another solc installation on the system taking precedence on the PATH. The documented remedy is to uninstall other installations of solc, with `brew install solidity` given as the example. The same fix is repeated in the section about solc-select version changes not being reflected in `solc --version`.

The Windows error, "Unsupported Platform", has a different cause and a different fix: an old solc-select or an old Python. The current stable release supports Windows, and the documented remedy is to upgrade:

pip install --upgrade solc-select

The two network-related issues are labelled as under investigation. On OS X, the SSL certificate verification failure is attributed to Python distributions on OS X having no certificates and being unable to validate SSL connections, described as a breaking change introduced in Python 3.6, with the suggested fixes being to install certifi and run the Install Certificates command. The connection refused issue is attributed to version 0.2.1 pulling older Linux binaries from a related repository, with ISP-level blocking of certain GitHub domains named as a possible cause, and the suggested workaround being to downgrade to 0.2.0.

All of that is worth knowing, but the practical takeaway is simpler. Install once, upgrade rather than downgrade, and make sure exactly one solc is on the PATH.

AGPL-3.0 and what the tool deliberately does not do

solc-select is licensed and distributed under the AGPLv3 licence, and the README points out that an exception to the terms can be requested by contacting the maintainers. For a build tool that people run on developer machines and in CI, that is a normal arrangement, but it is a strong copyleft licence and worth checking against your organisation's policy if you intend to vendor or modify it. This is a description of the licence, not legal advice.

It is also worth being clear about what the tool does not do. It does not compile your Solidity, it does not manage a Foundry, Hardhat or brownie configuration, and it does not resolve imports. Its entire job is to put the right official binary in place and make `solc` mean the version you asked for. If your workflow already pins a compiler inside a container image, solc-select adds a second source of truth rather than removing one.

The project is not archived and the last push was on 2026-06-04, with releases v1.2.0 from 2025-12-04, v1.1.0 from 2025-04-18 and v1.0.4 from 2023-06-26. The default branch is dev rather than main, which is worth knowing if you are pinning a branch.

The repository itself is small and conventionally laid out: a `solc_select/` package directory, a `tests/` directory, `run_tests.py`, a `Makefile`, a `CODEOWNERS` file, `funding.json`, a `.pre-commit-config.yaml` and a `uv.lock`. The development extra installs pytest with coverage and xdist, ruff and mypy for linting and type checking, and pre-commit, so the project runs a conventional Python quality stack.

Editorial conclusion

Adopt solc-select if your team works across several Solidity versions at once, because it downloads the official binaries rather than building compilers and gives you a per project switch through SOLC_VERSION. Do not adopt it if you already pin one compiler through your package manager or a build image, and do not expect it to work on every architecture without reading the version ranges: Apple silicon needs Rosetta below 0.8.5 and Linux ARM needs QEMU below 0.8.31. Verify first that no other solc is installed on your PATH, since the documentation says duplicate installations are the cause of a solc --version that does not match what you selected.

Frequently asked questions

Official sources

1. crytic/solc-select on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases