# How to rename a generated SDK package and its import path

> Set the npm, PyPI, and Go names of a generated SDK in configuration, regenerate from clean, install each package in a throwaway consumer, and grep for the old names.

Source: https://voxgig.com/howto/change-a-generated-package-name-and-import-path

- Audience: library-maintainer
- Level: intermediate
- Languages: typescript, go, python
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

Set the names in the generator's configuration and regenerate from clean. In sdkgen, four keys in .sdk/model/project.aontu set the npm and PyPI names and the Go module path and package. The Python import name follows the project name, so scaffold under the name you want. openapi-python-client takes project_name_override and package_name_override, and OpenAPI Generator takes packageName, npmName, and the git options. Then import each package and grep for the old names.

---
## You will need

Node 22 or later and a generated SDK you can regenerate from clean. Go and Python run the
consumers. This page scaffolds sdkgen projects from the five-operation Bookshelf document with
`ts`, `go`, and `py` targets, and runs the other two generators on the same document. The names
it moves to are `@acme/shelf-client`, `acme-shelf-client`, and `github.com/acme/shelf-client/go`.
`read-names.mjs` reads each generated tree's manifests and counts the files that still carry an
old name.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [A post-generation rename script](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/sed.html) | The generator has no key for the name and you cannot wait for one | It runs after every generate, and any spelling it misses ships under the old name | The generator has a key, which survives regeneration |
| [Kiota class name and namespace flags](https://learn.microsoft.com/en-us/openapi/kiota/using) | A Kiota client inside your own project, with no package of its own | `--class-name` and `--namespace-name` set the client class and its namespace or module; the using page lists no package-name flag | You publish the client as its own package |
| [OpenAPI Generator additional properties](https://openapi-generator.tech/docs/usage/) | One tool generates several languages, each from its own command line | A different key per generator, and the git options repeated, or placeholders stay | One name should reach every language from one place |
| [`openapi-python-client` overrides](https://github.com/openapi-generators/openapi-python-client) | A Python client whose distribution and import names you want to set apart | Python only, so every other language's name lives in another tool's config | You ship the same SDK in other languages |
| [sdkgen project.aontu keys](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | An sdkgen project whose npm, PyPI, and Go names differ from the derived ones | Four keys cover npm, PyPI, and Go; the Python import follows the project name alone | The Python import must differ from the project name |

Voxgig maintains sdkgen. It is one of five rows here, and its row says where it stops.

A rename script is the option the others exist to replace: it repeats on every run and misses
what it does not spell out. `openapi-python-client` sets both Python names from two keys and
nothing else. OpenAPI Generator covers more languages at the price of one option set per generator.
sdkgen holds every target's names in one file, except the Python import.

## Read the names sdkgen derives and set your own

A scaffold derives every name from two values in `.sdk/model/sdk.aontu`: the project name,
`bookshelf` here, and the origin, `voxgig-sdk`. The
[model reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) lists the
keys that override them, and they go in `project.aontu`, the overlay the scaffold never
overwrites:

```aontu title="project-names.aontu"
# Package names and import paths, held once for every target.
main: kit: repo: { host: 'github.com', path: 'acme/shelf-client' }
main: kit: target: ts: publish: registry: package: '@acme/shelf-client'
main: kit: target: py: publish: registry: package: 'acme-shelf-client'
main: kit: target: go: module: { path: 'github.com/acme/shelf-client/go', package: 'shelfclient' }
```

`generate.sh` appended that block to a bookshelf project, generated again, then tried two ways of
renaming the project itself. `names.mjs` prints what each tree carried.

```bash
node names.mjs sdkgen
```

```text output
scaffolded as bookshelf
  npm @voxgig-sdk/bookshelf-sdk
  PyPI voxgig-sdk-bookshelf-sdk
  import py/bookshelf_sdk
  Go module github.com/voxgig-sdk/bookshelf-sdk/go
  Go package voxgigbookshelfsdk
  files naming an old name: @voxgig-sdk/bookshelf-sdk in 4, voxgig-sdk-bookshelf-sdk in 2, github.com/voxgig-sdk/bookshelf-sdk in 66, voxgigbookshelfsdk in 1, bookshelf_sdk in 51
the four keys in project.aontu
  npm @acme/shelf-client
  PyPI acme-shelf-client
  import py/bookshelf_sdk
  Go module github.com/acme/shelf-client/go
  Go package shelfclient
  files naming an old name: bookshelf_sdk in 51
renamed to shelf in sdk.aontu, generated again
  npm @acme/shelf-client
  PyPI acme-shelf-client
  import py/shelf_sdk
  Go module github.com/acme/shelf-client/go
  Go package shelfclient
  files naming an old name: bookshelf_sdk in 1
  files left behind in py/bookshelf_sdk: 4
scaffolded as shelf, the same four keys
  npm @acme/shelf-client
  PyPI acme-shelf-client
  import py/shelf_sdk
  Go module github.com/acme/shelf-client/go
  Go package shelfclient
  files naming an old name: none
```

The four keys moved npm, PyPI, and both Go names, and left the Python import as `bookshelf_sdk` in
51 files. No key reaches it: 16 of the Python target's 28 components write it as the project
name plus `_sdk`, `Config_py.ts` at line 116 as `model.const.Name.toLowerCase() + '_sdk'`. Setting
`main: kit: target: py: module: name` in `project.aontu` stopped the build with a unification
conflict, because the project's `.sdk/model/target/py.aontu` already sets it to `'bookshelf'`. `@voxgig/sdkgen` 4.45.0, which a scaffold does
not install, gave the same 51 files.

So the project name is the lever for Python, and it renames classes in every target with it,
`BookshelfSDK` to `ShelfSDK`. Changing it in place in `sdk.aontu` left four files behind in
`py/bookshelf_sdk/`: `bookshelf_types.py`, `config.py`, `schema.py`, and `utility/prepare_auth.py`. Scaffolding under the name `shelf` with the same four keys left none.

## Import each package from a throwaway consumer

`generate.sh` built and installed each renamed package outside its tree: the TypeScript SDK from
`npm pack`, the Go module through a `replace` directive, and the Python packages into
separate virtual environments with uv.

```bash
node consumers.mjs
```

```text output
sdkgen, TypeScript, installed from npm pack
  ts require("@acme/shelf-client") function
sdkgen, Go, through a replace directive
  go import "github.com/acme/shelf-client/go" *core.ShelfSDK
sdkgen, Python, installed with uv
  py import shelf_sdk ok: True
  py distribution acme-shelf-client 0.0.1
openapi-python-client, Python
  py import acme_shelf ok: True
  py distribution acme-shelf-client 1.0.0
OpenAPI Generator, Python
  py import acme_shelf ok: True
  py distribution acme-shelf-client not installed
  py distribution acme-shelf 1.0.0
```

## Set the same names in the two other generators

`openapi-python-client` reads `project_name_override` and `package_name_override` from the file
given with `--config`, as its README documents. The first names the distribution and the output
directory, the second the import package.

```yaml title="opc-config.yaml"
project_name_override: acme-shelf-client
package_name_override: acme_shelf
```

```bash
node names.mjs opc
```

```text output
no config
  PyPI bookshelf-client
  import bookshelf_client
  files naming an old name: bookshelf_client in 3, bookshelf-client in 4
opc-config.yaml
  PyPI acme-shelf-client
  import acme_shelf
  files naming an old name: none
```

OpenAPI Generator takes a different key per generator: `packageName` for
[python](https://openapi-generator.tech/docs/generators/python/) and
[go](https://openapi-generator.tech/docs/generators/go/), and `npmName` for
[`typescript-fetch`](https://openapi-generator.tech/docs/generators/typescript-fetch/), which writes
no `package.json` without it. The Go module path comes from `--git-host`, `--git-user-id`, and
`--git-repo-id`, global options whose placeholders otherwise stay in the README, the push script, or the manifest.

```bash
node names.mjs oag
```

```text output
python, no options
  PyPI openapi_client
  import openapi_client
  files naming an old name: openapi_client in 19, GIT_USER_ID in 3, GIT_REPO_ID in 3
python, packageName and projectName
  PyPI acme_shelf
  import acme_shelf
  files naming an old name: GIT_USER_ID in 3, GIT_REPO_ID in 3
go, no options
  Go module github.com/GIT_USER_ID/GIT_REPO_ID
  Go package openapi
  files naming an old name: GIT_USER_ID in 5, GIT_REPO_ID in 5
go, packageName and the three git options
  Go module github.com/acme/shelf-client
  Go package shelfclient
  files naming an old name: none
typescript-fetch, no options
  no package manifest
  files naming an old name: none
typescript-fetch, npmName
  npm @acme/shelf-client
  files naming an old name: GIT_USER_ID in 1, GIT_REPO_ID in 1
```

## Check it worked

The test runs `read-names.mjs` on a small tree it builds, with a test package, a nested module and
a `.sdk` folder that must not count. It then checks every recorded tree and consumer against the
names in `project-names.aontu` and `opc-config.yaml`.

```bash
node --test names.test.mjs
```

```text output
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

## When it goes wrong

The Python package installs and imports under its old name. The name came from the project, and
the keys never reached it. Grep the output for the old import name after every rename.

The old package is still there after a rename. Generating again in the same tree removed most of
`py/bookshelf_sdk/` and kept four files, so the tree carries a package nothing generates. Regenerate from
clean, a fresh scaffold or an emptied output directory, before you build.

OpenAPI Generator's `python` generator, on its default `urllib3` library, installs the package as
`acme-shelf`, not `acme-shelf-client`. Its options page scopes `projectName` to `setup.py`, and the
`pyproject.toml` that the installer read takes its name from `packageName`.[^1] Set `packageName` to the import name you want,
and check the distribution name a consumer sees.

`GIT_USER_ID` stays in the output of a generator run without the git options: three files of the
Python run here, and the `package.json` of the TypeScript run. Pass the three options to every
generator.

## When not to do this

Do not rename with a script over the output when the generator has a key. The next generate puts
the old name back, and the script only knows the spellings you gave it.

Do not expect sdkgen's project file to rename the Python import. If that name must differ from the
project name, choose the project name for it at scaffold time, and accept that the class names
follow.

`openapi-python-client` is the cleaner tool for a Python-only client whose distribution name and
import name differ, because it sets both from two keys and left nothing behind here. OpenAPI
Generator fits a team that already drives each language from its own command line or config file,
so a key per generator costs it little.

Do not publish under a new name without a release note. To a consumer, a renamed package is a new
dependency, and the old one stops receiving fixes.

## Related how-tos

- [Rename a generated SDK method without editing the output](/howto/rename-generated-methods-without-editing-output)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Add a custom feature that survives SDK regeneration](/howto/add-a-custom-feature-to-a-generated-sdk)

- [Switch SDK generators without breaking published packages](/howto/migrate-from-openapi-generator-without-breaking-packages)

## Last verified

Verified 2026-11-21 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen`
4.44.3 and 4.45.0, `@voxgig/apidef` 8.32.4, `openapi-python-client` 0.30.0, and OpenAPI Generator
7.27.0 on OpenJDK 21.0.13. `generate.sh` ran once, with network access, on Go 1.24.7 and Python
3.13.18 with uv 0.11.32. It generated every tree, built and installed each consumer, and wrote
the JSON and text records under `generated/`. The gate re-runs only the commands on this page,
which print those records, and the test. Kiota was not run for this page; its flags come from its
using page.

[^1]: Python's [name normalization](https://packaging.python.org/en/latest/specifications/name-normalization/)
rule puts a name in lowercase and replaces every run of `.`, `-`, and `_` with one `-`, so `acme_shelf`
and `acme-shelf` are one distribution to an installer. `acme-shelf-client` normalizes to itself,
so the rule leaves it a different name.