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. When
an old compiler cannot produce a modern validation output format, that format is
dropped and reported as unavailable. Writes then remain blocked unless the
source-validation gap is explicitly accepted with --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 (default0.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, switching legacy forwarders, 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--writeadditionally requires a closure destination.--closure-output DIR— write the validated upgraded closure (project + dependencies, laid out import-root-relative sovyper -p DIRresolves 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-levelinterfaceblocks into sibling.vyifiles 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.--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 about0.4.xrules.--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 (default120).--network-timeout SECONDS— time budget for provisioning each compiler environment: interpreter selection, downloads, and installs (default300). 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— write despite a storage-layout comparison mismatch.--config PATH— read configuration from a specificpyproject.toml.
JSON reports include a top-level schema_version. 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, 5, and 6. 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—--checkfound 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,VY126removesinitializes: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-dependenciesto migrate redundant nested initializations too. - 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.0b2back through the0.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.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vyupgrade-0.10.0.tar.gz | 152.6 kB | With provenance | Details for vyupgrade-0.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vyupgrade-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for vyupgrade-0.10.0-py3-none-any.whl |
Total release size: 330.1 kB
Release files / vyupgrade-0.10.0.tar.gz
| Download URL | vyupgrade-0.10.0.tar.gz |
|---|---|
| Size | 152.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d855b5cba7a752c3f61eb30c910f9e72a5e19801d286002fa432c063cf59a5ef
|
|
BLAKE2b-256 checksum How to use checksums |
e0e59fc62a954b553373932797bbf4319fd4d561272f157212815f957f9c0314
|
| 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 7, 2026.
Transparency logRelease files / vyupgrade-0.10.0-py3-none-any.whl
| Download URL | vyupgrade-0.10.0-py3-none-any.whl |
|---|---|
| Size | 177.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a25bb7994e4726c0e553b689ae3a9c9e91c903ad3aa66ccc5582d1effedc99b9
|
|
BLAKE2b-256 checksum How to use checksums |
400201b5e090b02f025b6e1fd4403f35f94222bf9a8d94a310c670d2384f7176
|
| 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 7, 2026.
Transparency logSecurity for vyupgrade 0.10.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.
Attestation for vyupgrade-0.10.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 7, 2026.
Transparency logA 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.