Skip to main content

vyupgrade

A compiler-backed tool for upgrading Vyper contracts across language versions. It rewrites legacy syntax to a chosen target compiler, then proves the rewrite is safe by compiling the source and the result and comparing their ABI, method identifiers, and storage layout.

It covers installable Vyper 0.1.0b* prereleases through 0.4.3, plus opt-in 0.5.0a1 through 0.5.0b2 prerelease targets. Rules are version-gated: a given rewrite only fires when the migration from the source version to the target version actually crosses the compiler release that introduced the change.

Install

Run it once without installing:

uvx vyupgrade contracts/

Or install it as a tool:

uv tool install vyupgrade
vyupgrade contracts/

Usage

Preview the changes as a unified diff:

vyupgrade contracts/ --diff

Apply them in place and write a machine-readable report:

vyupgrade contracts/ --write --report-json vyupgrade-report.json

Fail without writing when files would change, for use in CI:

vyupgrade contracts/ --check

The target defaults to 0.4.3; pass --target-version to migrate to a different release, including an explicit prerelease target such as 0.5.0b2.

Paths may be files or directories; directories are searched recursively for .vy and .vyi sources. The source version is inferred per file from its #pragma version (or legacy # @version) line. Pass --source-version to override the inference for files that have no pragma.

Rule gating for broad source pragmas uses the oldest satisfying compiler so historical migrations still run. Unless --source-vyper overrides discovery, source-validation authority is the nearest project's declared Vyper resolution (including its lock), then an exact pragma, then the newest known compiler that satisfies a ranged pragma without exceeding the requested target. Ranged selection never inspects source syntax.

How it validates

For each file, vyupgrade compiles the original under its source compiler and the rewritten output under the target compiler, then compares the two artifacts. A migration is only written back when every file still compiles under the target, the source validation succeeded, every required artifact is available, and ABI, method identifiers, and storage layout compare equal. This write decision is independent of diagnostic selection and rule version gating. Standalone .vyi inputs are target-compiled through a generated import harness.

Compiler subprocesses run through the bundled uv. Files in a project use the nearest declared environment via uv run --isolated --project: the project's main dependencies plus each extra or dependency group that declares its Vyper requirement. Other groups and extras, such as test or lint tooling, are not installed, so a tool that cannot build on the current platform does not block compilation. An existing uv.lock that still matches its manifest (uv lock --check) is enforced with --frozen. An unlocked project, or one whose lock is stale, is mirrored into a temporary root without the lock so resolution cannot create or rewrite a lockfile in the source tree. Files without a project use an isolated uv run --no-project --with vyper==<version> environment. Dependencies are never guessed from imports or compiler errors.

Vyper releases before 0.3.1 run under Python 3.8 with a setuptools release that still provides the pkg_resources module those compilers import. For 0.1.0b* source compilers, vyupgrade also runs the compiler through a typed-ast compatibility wrapper so the legacy compiler sees pre-Python-3.8 AST node classes without requiring a local Python 3.6 or 3.7 interpreter. For source compilers before 0.2.16, vyupgrade omits the unsupported layout request. When ABI and method identifiers were compared, --allow-storage-layout-change accepts the unchecked source layout. Some early beta compilers also lack AST or method identifier output, or use older output conventions. Other source validation gaps require --allow-unvalidated-source. Target compilers must produce every requested validation output.

Source and target validation require deployment bytecode generation for entry contracts as well as the comparison artifacts. Imports and source bytes are captured once and reused for source compilation, target validation, and closure export. Overlays preserve dependency bytes exactly: they do not repair imports, pragmas, or interface bodies. If dependencies also need upgrading, use --include-dependencies with --closure-output or --closure-archive. Unchanged dependency inputs are rechecked before an in-place write. Optional --format mamushi runs only against temporary staged candidates. The formatted bytes are read back into the migration plan, compiled again under the target compiler, and compared before any destination is changed. Formatter failure leaves every original untouched.

Writes recheck all planned inputs, reject generated symlinks and unsafe hard-linked or read-only replacements, and roll back already replaced files when a later write fails. Multi-file replacement is rollback-aware rather than globally atomic; a non-cooperating external writer can still race the final portable filesystem check. Reports distinguish original, validated candidate, and final on-disk hashes. If a post-write test command changes a planned file, the run exits nonzero and records the drift.

Source-validation evidence records the declared spec, actual resolved compiler, dependency context, whether the compiler started, a typed failure origin, and the compiler process output. compiler_output contains only compiler stdout and stderr; environment-manager or adapter diagnostics remain separate.

Options

  • --target-version — target Vyper version or spec (default 0.4.3).
  • --source-version — override the per-file inferred source version.
  • --strip-pragma — remove version pragmas from migrated source instead of rewriting or adding one; target compiler selection and compiler-backed validation are unchanged.
  • --diff — print a unified diff instead of the report.
  • --write — apply changes in place only after the validation decision passes.
  • --check — exit non-zero if any file would change; write nothing.
  • --aggressive — enable rewrites that change behavior or are not provably safe (e.g. enum → flag, widening interface return bounds for Vyper 0.5, changing external call mutability or ETH acceptance, switching legacy forwarders, merging distinct named reentrancy locks into the global lock, or converting a max-length array to a mapping). The array conversion also requires a storage-layout waiver before writing.
  • --include-dependencies (alias --upgrade-closure) — also upgrade and cross-validate the resolved import closure, including dependencies found via --compiler-search-paths; dependency modules are analyzed with compiler ASTs but validated through their consumer roots, and dependency sources are never rewritten in place, so --write additionally requires a closure destination.
  • --closure-output DIR — write the validated upgraded closure (project + dependencies, laid out import-root-relative so vyper -p DIR resolves every import) into DIR; requires --include-dependencies; overwrites files inside DIR, never deletes extras, never modifies dependency sources in place.
  • --closure-archive OUT.vyz — emit the validated upgraded closure (dependencies bundled) as a single Vyper archive via the target compiler; requires --include-dependencies, a target >= 0.4.0, and exactly one entry contract.
  • --split-interfaces — move top-level interface blocks into sibling .vyi files and import them.
  • --select / --ignore — comma-separated rule codes to include or exclude.
  • --report-json PATH — write a JSON report of fixes, diagnostics, and validation results. Use a path separate from migration inputs and outputs. The command can replace an existing report bearing vyupgrade producer metadata.
  • --format mamushi — format staged candidates, then revalidate the exact output before writing.
  • --test-command CMD — run a test command after a successful write, record its result, and fail when it does not pass.
  • --enable-decimals — treat decimals as enabled when reasoning about 0.4.x rules.
  • --source-vyper / --target-vyper — pin the exact compiler version for each side.
  • --source-python / --target-python — pin the Python interpreter for each compiler subprocess.
  • --compiler-search-paths — extra import search paths for the compiler.
  • --compiler-timeout SECONDS — time budget for each compile, measured after its environment is provisioned (default 120).
  • --network-timeout SECONDS — time budget for provisioning each compiler environment: interpreter selection, downloads, and installs (default 300). Raise it on slow or cold CI hosts.
  • --allow-unvalidated-source — write despite a failed source compile or unavailable source artifacts.
  • --allow-abi-change — write despite an ABI comparison mismatch.
  • --allow-method-id-change — write despite a method-identifier comparison mismatch.
  • --allow-storage-layout-change — accept a storage-layout comparison mismatch, or an unavailable source layout on Vyper before 0.2.16 when ABI and method identifiers were compared.
  • --config PATH — read configuration from a specific pyproject.toml.

JSON reports include a top-level schema_version. Version 7 states each source and package inventory once, so reports grow linearly with the number of files. The top-level source_sets object maps a declared snapshot digest to its source identities; each attestation's declared_spec keeps snapshot.sha256 and no longer lists sources. The digest is SHA-256 over each source's path, a NUL byte, its SHA-256 and a NUL byte, in path order. The top-level package_sets object maps a package-set digest to its resolved packages; each attestation's dependency_context replaces resolved_packages with that digest in resolved_packages_sha256, which is SHA-256 of the list's JSON encoding with sorted keys, no whitespace and non-ASCII characters escaped (Python's json.dumps(packages, sort_keys=True, separators=(",", ":"))). Consumers can recompute both digests from the referenced entries. Version 6 adds per-file source_error_type and target_error_type fields containing the Vyper exception class name when the managed compiler exposes one. Compiler process return codes remain available in each source or target attestation's exit_status.code. Version 5 distinguishes direct contract validation from dependency validation attributed through one or more consumer roots. Dependency reports list those roots and summarize their compile outcomes without claiming standalone compiler attestations. Version 4 provides producer identity plus separate source and target validation attestations. Each attestation records the declared source snapshot and compiler declarations, compiler authority and identity, dependency context, process completion and exit status, validated sources, the exact compile attempt, typed failure origin, and compiler output when validation fails. Version 2 added a per-file role and a top-level closure object; version 3 first introduced source-validation evidence and is superseded by versions 4 through 7. Consumers should treat a missing version as the legacy unversioned format and require a new schema version before relying on renamed, removed, or type-changed fields.

Configuration

Defaults can live in pyproject.toml under [tool.vyupgrade]. Command-line flags take precedence. Configuration errors stop the run with exit code 4: keys and value types are checked, booleans must be unquoted true or false, and explicit --config paths must exist.

[tool.vyupgrade]
paths = ["contracts/"]
target-version = "0.4.3"
source-version = "infer"
strip-pragma = false
report-json = "vyupgrade-report.json"
aggressive = false
split-interfaces = false
format = "none"
allow-unvalidated-source = false
allow-abi-change = false
allow-method-id-change = false
allow-storage-layout-change = false
compiler-timeout = 120
network-timeout = 300

Exit codes

  • 0 — success.
  • 1 — --check found files that would change.
  • 2 — target compilation or required target artifacts failed validation.
  • 3 — source compilation or source artifact availability failed validation.
  • 4 — usage error (no paths, or conflicting flags).
  • 5 — an error-severity diagnostic was raised.
  • 6 — the requested formatter failed or could not be run.
  • 7 — an unwaived ABI, method-identifier, or storage-layout mismatch blocked the write.
  • 8 — the post-write test command failed, timed out, or could not start.
  • 9 — migration planning or the rollback-aware write transaction failed.

Coverage

Rewrites carry a VY### code and diagnostics a VYD### code. Where the source intent cannot be proven safe, the change is reported as a manual-review diagnostic instead of being applied.

  • For upgrades crossing 0.5.0b2, VY126 removes initializes: of stateless imported modules using the captured import closure. Stateful or abstract modules, unresolved imports and ambiguous imports with any stateful candidate retain their declarations. Use --include-dependencies to migrate redundant nested initializations too.
  • For upgrades crossing 0.5.0a2, VY125 uses managed Vyper 0.4.3 annotations to replace exceeded interface return bounds with .... Each affected call in the captured closure must return directly from a function or initialize a variable whose annotation specifies the original type. VYD022 and VYD023 report incomplete caller evidence or unresolved bounds. Use --aggressive --ignore VY125 to select the existing VY124 widening instead.
  • For upgrades crossing 0.4.0, VY080 preserves the legacy blueprint offset, and VY224 preserves non-ASCII return and revert bytes for compiler-confirmed literal contexts. VYD024 identifies other literals that need review.
  • For 0.5.0a3 and 0.5.0b1 sources migrating to 0.5.0b2, VY127 uses the source compiler's annotated declaration to name positional custom error arguments, including errors defined in imported Vyper modules.
  • Managed Vyper 0.3.10 supplies external call modes and return types during source compilation. Other compilers can use block-scoped analysis to resolve local receivers. VYD025 flags an interface change that could affect outgoing calls or make an entry point accept ETH. Compiler-backed rewrites
  • docs/migration-coverage.md — every syntax change mapped to a rule, diagnostic, explicit no-op, or validation-only behavior.
  • docs/vyper-syntax-history.md — the versioned Vyper syntax history from 0.5.0b2 back through the 0.1.0b* prereleases, with PR links and before/after examples.
  • CHANGELOG.md — release notes.
  • DEVELOPMENT.md — maintainer validation and release workflow.

Metadata

Release files for vyupgrade 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vyupgrade 0.11.0
File Size Uploaded Provenance Actions
vyupgrade-0.11.0.tar.gz 183.2 kB With provenance Details for vyupgrade-0.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vyupgrade 0.11.0
File Interpreter ABI Platform Actions
vyupgrade-0.11.0-py3-none-any.whl Python 3 none any Details for vyupgrade-0.11.0-py3-none-any.whl

Total release size: 393.0 kB

Release files / vyupgrade-0.11.0.tar.gz

Download URL vyupgrade-0.11.0.tar.gz
Size 183.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ef8c6f2cea2cf98e23c0ff6a1545f1a81791fb1987ecd43885a6eedd024570a4
BLAKE2b-256 checksum
How to use checksums
5ebd51483132089c48986f64306a5b544e41a72d655becf4b42cd79f3db13e34
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / vyupgrade-0.11.0-py3-none-any.whl

Download URL vyupgrade-0.11.0-py3-none-any.whl
Size 209.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f7d47cf4cea15876c4233482b81e4787420751f7110d8ff60bf71c6690943a1f
BLAKE2b-256 checksum
How to use checksums
8a1feb943f3b5545a222ffcd865cb12403adacb2c9d315a4eb6e7aedea1b4675
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for vyupgrade 0.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vyupgrade-0.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page