toolchain.toml

The toolchain.toml file declares which toolchains your project needs.

Basic Structure

[toolchains]
go = {}
rust = {}
python = {}

Each key under [toolchains] is a toolchain name that will be resolved from the registry.

buck2 is not declared here. Turnkey ships its own pinned buck2 release to the shells that have the Buck2 integration, and declaring buck2 or buck2-toolchain is an error. See The buck2 version.

Version Pinning

You can pin specific versions when the registry provides multiple versions:

[toolchains]
go = { version = "1.22" }      # Pin to Go 1.22
python = { version = "3.11" }  # Pin to Python 3.11
rust = {}                       # Use registry default

If no version is specified, the registry's default version is used.

Available Toolchains

Languages

go - Go compiler and tools
rust - Rust compiler (rustc)
cargo - Cargo package manager
clippy - Rust linter
rustfmt - Rust formatter
rust-analyzer - Rust LSP server
python - Python interpreter
uv - Python package manager
ruff - Python linter and formatter
nodejs - Node.js runtime
typescript - TypeScript compiler
biome - Fast linter/formatter for JS/TS/JSON

Solidity

solc - Solidity compiler
foundry - Ethereum dev toolkit (forge, cast, anvil)

Other Tools

nix - Nix package manager
reindeer - Rust Buck2 target generator
jsonnet - Jsonnet to JSON compiler
mdbook - Documentation tool
tk - Turnkey CLI wrapper for buck2

Dependency generators (godeps-gen, rustdeps-gen, pydeps-gen, jsdeps-gen, soldeps-gen) are automatically included when their corresponding language is enabled. You don't need to list them in toolchain.toml.

For example, if you have go = {} in your toolchain.toml and buck2.go.enable = true in your flake.nix, godeps-gen will automatically be available in your shell.

Example Configurations

Minimal Go Project

[toolchains]
go = {}

Full-Stack Project

[toolchains]
# Backend
go = {}
python = {}

# Frontend
nodejs = {}
typescript = {}
biome = {}

# Development
nix = {}

Pinned Versions

[toolchains]
go = { version = "1.22" }
python = { version = "3.11" }
nodejs = { version = "20" }
rust = { version = "1.75" }

Custom Registries

The registry mapping toolchain names to packages can be customized in your flake.nix. See Registry Pattern for details on:

Adding custom toolchains via registryExtensions
Creating reusable registry overlays
Multi-version toolchain support

Turnkey User Manual