# Replace Deprecated io/ioutil With os and io in a Go Program

Yes. An agent replaces every io/ioutil call with its os or io equivalent, raises the go directive only as far as needed, and handles the one call that changes type.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-ioutil-to-os-and-io/ioutil/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

Go moved everything in `io/ioutil` to the `os` and `io` packages in 1.16 and later marked the package deprecated. Most of the move is a rename, and the agent starts by sorting the calls into those that are and those that are not. In a program like perkeep/gphotos-cdp, which downloads a Google Photos library by driving Chrome, `main.go` imports `io/ioutil` on line 27 and calls it five times: `ioutil.ReadFile` in `getLastDone`, `ioutil.TempDir` in `NewSession`, `ioutil.WriteFile` in `markDone`, and `ioutil.ReadDir` twice, in `cleanDlDir` and in the loop inside `download` that waits for a file to finish.

Three of those are renames with the same signature: `os.ReadFile`, `os.WriteFile` and `os.MkdirTemp`. Before making them the agent reads `go.mod`, because the new names do not exist in every release. This module says `go 1.12`, four releases before the functions arrived. So the first change is to the `go` directive, and the agent raises it to the lowest version that has the replacements, or to the version your CI builds with if that is higher, and says which and why. The same line explains why no linter complained: staticcheck holds back a deprecation finding until the module's declared Go version reaches the release it dates the deprecation from. With `go 1.12` it prints nothing for this file, and it stays silent at 1.16 as well. From a directive of 1.19 it reports `io/ioutil has been deprecated since Go 1.19` under check SA1019.

`ReadDir` is the call that is not a rename. `ioutil.ReadDir` returns `[]os.FileInfo`; `os.ReadDir` returns `[]os.DirEntry`, a lighter value that knows the name and whether the entry is a directory but has not looked up size or modification time. In `cleanDlDir` the loop only calls `IsDir()` and `Name()`, so the swap compiles and behaves the same. In `download` it does not compile: the loop appends entries to a `[]os.FileInfo` and later reads `fileEntries[0].Size()` to tell whether a download is still growing, and the compiler rejects the append because `DirEntry` has no `ModTime`. The fix is to call `Info()` on the entry, which returns the `FileInfo` and an error.

That error is where the behaviour can change, and the agent writes the handling deliberately. The loop is watching a directory in which Chrome renames a `.crdownload` file to its final name when the transfer completes. An entry can therefore vanish between the directory listing and the `Info()` call, and `Info()` then returns an error for which `errors.Is(err, fs.ErrNotExist)` is true. The old function looked up each file as part of the listing and gave the caller no error for an entry that disappeared in between. If the port returns every `Info()` error, a download that finishes at the wrong instant becomes a failed run. The agent treats a not-exist error as an entry to skip, so the loop comes round again and sees the renamed file, and returns any other error as before. It then runs `go build ./...` and `go vet ./...` and reports what vet already says about this file, an unreachable statement on line 242, without touching it.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Replace the deprecated io/ioutil package in this Go module with its replacements in os and io. Read go.mod first: the replacements need Go 1.16 (os.ReadFile, os.WriteFile, os.ReadDir, os.MkdirTemp, os.CreateTemp, io.ReadAll, io.Discard, io.NopCloser). If the go directive is older, raise it to the lowest version that works, or to the version the CI workflow or Dockerfile builds with if one is pinned, run go mod tidy, and explain the choice and any change it caused in go.mod and go.sum. List every ioutil call with its file, line and enclosing function. Apply the same-signature renames. For each ioutil.ReadDir, read how the result is used: if the code needs Size, Mode or ModTime, call Info() on the DirEntry and handle its error; when the directory can change while it is being read (downloads, temp files, logs), treat an fs.ErrNotExist from Info() as an entry to skip and say so in a comment, and return any other error. Note that os.ReadDir sorts by filename as ioutil.ReadDir did. Remove the import. Do not refactor anything else. Run gofmt, go build ./..., go vet ./... and the tests if there are any; if there are none, say so. Install staticcheck and run check SA1019 before and after; if it reports nothing before your change, say whether the go directive is the reason. Report other findings without fixing them. Open a pull request with the list of calls, the build and vet output, and the staticcheck output before and after.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that changes `main.go` and `go.mod`, and `go.sum` if tidying under the new directive alters it. The description has a table of the five calls: function, old call, new call, and whether the signature changed. Four rows say no. The row for the loop in `download` links to the new `Info()` block and explains the skip on a missing file in two sentences. Below it are the `go build` and `go vet` results and what staticcheck said before and after, with a note when a low `go` directive is the reason it said nothing.

A reviewer spends their time on that one row. They check that the skip applies only to a not-exist error and that the rest of the loop, the deadline that moves while the file size grows and the `.crdownload` suffix test, is unchanged. They also decide whether the new `go` directive suits them, since it sets the minimum toolchain for anyone who builds the module. The description says this repository has no test files, so the evidence is a clean build and vet, not a passing suite, and it does not pretend otherwise.

## Run it on every Linear issue labelled tech-debt

Deprecation cleanups tend to live in a tracker as small tickets nobody picks up. Connect Linear under Settings → Connections, then add an automation on the Project with a `linear` trigger on `linear.issue.labeled`, your label, and the prompt above. The issue that gained the label is added after the prompt as event text. It fills in nothing in the prompt, so write the prompt to stand on its own, as this one does.

The trigger fires when a member of your Rush org applies the label, and each labelled issue starts one run. For a group of services, one automation per Project with the same prompt gives one pull request per module, and the automation's max runs per hour caps a bulk relabel.

## Why run it on Rush?

This is a cleanup that looks too small to plan and is therefore done by search and replace, which is how the `Info()` error ends up returned, ignored or dropped with a blank identifier. Getting it right means reading what each directory listing is used for and what else is writing to that directory. The agent reads the surrounding function for every call, and it compiles after each step in a sandbox with a current Go toolchain, so the type error that marks the interesting call is in the run's record and not something a reviewer has to rediscover.

It also answers the toolchain question with evidence. Raising a `go` directive on a hunch can change `go.mod` more than expected. The agent runs `go mod tidy` under the version it proposes and shows the resulting diff, so the cost of the directive change is visible in the same pull request as the benefit.

## Frequently asked questions

### Is io/ioutil going to be removed?

No. Go's compatibility promise keeps the package in the standard library, and since 1.16 its functions are thin wrappers around the ones in `os` and `io`. The reasons to move are that linters flag it once your module declares a recent Go version, and that `os.ReadDir` avoids a file lookup per entry when you only need names.

### What is the difference between ioutil.ReadDir and os.ReadDir?

The return type. `ioutil.ReadDir` gives `[]fs.FileInfo`, with size and times already fetched for every entry. `os.ReadDir` gives `[]fs.DirEntry`, which has `Name()`, `IsDir()` and `Type()`, and an `Info()` method that fetches the rest on request and can fail. Both return entries sorted by filename.

### Why did my linter not warn about ioutil?

Check the `go` line in `go.mod`. staticcheck holds back a deprecation warning when the declared language version is older than the release that deprecated the API, because the module may still need to build with an older toolchain. For `io/ioutil` that release is 1.19, so a directive of 1.16 is enough to use the replacements and still too low for the warning.

### Does it update vendored or generated code?

No. Files under `vendor/` belong to your dependencies and change when you upgrade them, and generated files are rewritten by their generator. The agent lists any `ioutil` imports it finds there, names the dependency or generator responsible, and leaves the files alone.

## More jobs like this: Turn a Linear label into a PR

- [Migrate From lib/pq to pgx in a Go API](https://getrush.ai/run/migrate-lib-pq-to-pgx/lib-pq/)
- [Migrate From Logrus to log/slog in a Go CLI](https://getrush.ai/run/migrate-logrus-to-slog/logrus/)
- [Migrate mkdirp to fs.mkdir with recursive: true](https://getrush.ai/run/migrate-mkdirp-to-fs-mkdir/mkdirp/)
- [Replace Moment.js With Day.js in an Express API](https://getrush.ai/run/migrate-moment-to-dayjs/moment/)
- [Replace pytz With zoneinfo in a Python Scraper](https://getrush.ai/run/migrate-pytz-to-zoneinfo/pytz/)
- [Migrate From querystring to URLSearchParams in a Node.js API Client](https://getrush.ai/run/migrate-querystring-to-urlsearchparams/querystring/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
