# PyNest gives FastAPI the module and decorator shape NestJS users expect

> PyNest is a Python framework layered on FastAPI that borrows NestJS modular conventions, dependency injection, decorators and a code generator, and it targets backend and ML engineers who want structured APIs. It is still version 0.6.2 with an IOC mechanism and an auth module listed as future work.

**PythonNest/PyNest** — PyNest is a Python framework built on top of FastAPI that follows the modular architecture of NestJS

- Repository: https://github.com/PythonNest/PyNest
- Website: https://pythonnest.github.io/PyNest
- Stars: 866 · Forks: 62
- Language: Python
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/pythonnest-pynest

## A re-imagining of NestJS for Python, not a translation

The project positions itself precisely, and the positioning is the first thing to understand. PyNest is a Python framework built on top of FastAPI that follows the modular architecture of NestJS, and the documentation is explicit that it is not a direct port of NestJS to Python but rather a re-imagining of the framework specifically for Python developers. The audience named is backend engineers and ML engineers, and the stated aim is to help them build better and faster APIs for data applications. That framing predicts the trade-offs you will find later. You get NestJS habits, decorators everywhere and generated module skeletons, but the underlying runtime is FastAPI with uvicorn, and several of the pieces that make NestJS feel coherent, such as an inversion of control mechanism and a ready-made authentication module, are still on the roadmap rather than in the box.

## The CLI writes the skeleton, then uvicorn serves it

Getting started is two commands and a generator. The package installs from PyPI:

```bash
pip install pynest-api
```

The generator then creates a project:

```bash
pynest generate application -n my_app_name
```

The result is a small tree with an app module, an entry point, a requirements file and a src package:

```text
├── app.py
├── main.py
├── requirements.txt
├── .gitignore
├── README.md
├── src
│    ├── __init__.py
```

You move into the directory and start the server:

```bash
cd my_app_name
```

```bash
uvicorn "app:app" --host "0.0.0.0" --port "8000" --reload
```

The last step matters for a first evaluation because it tells you the whole stack in one line: the generated app module is named app, the ASGI object inside it is also named app, and the server is plain uvicorn with reload enabled. The documentation then points you at the OpenAPI page at http://localhost:8000/docs to confirm the default API documentation is served.

## generate resource self-registers a five file module

Adding a feature is a second generator call:

```bash
pynest generate resource -n users
```

That creates a resource called users under the src folder, and the generated layout is the interesting part:

```text
├── users
│    ├── __init__.py
│    ├── users_controller.py
│    ├── users_service.py
│    ├── users_model.py
│    ├── users_entity.py
│    ├── users_module.py
```

Controller, service, model, entity and module, the same separation NestJS asks for, with the underscore naming convention that Python projects tend to use. The documentation states that the users module will immediately register itself with the application and be available for use, so registration does not need a manual import list. After that, routes and other application components are defined with decorators and other PyNest constructs. The practical effect is that a new feature arrives as a working set of files wired into the app, and what you have to fill in is the behaviour inside the service and the schema in the model.

## Dependency injection built on the injector library

The dependency injection story is what separates this from a file naming convention. PyNest supports dependency injection, and the documentation describes injecting services and providers into controllers using decorators, which makes the code easier to manage and easier to test. The implementation leans on libraries rather than inventing its own machinery: the project dependencies in pyproject.toml include injector, pinned to the 0.22 series, alongside click for the CLI, astor, pyyaml, fastapi, pydantic and uvicorn, with black in the list as well. The stated benefit is testability, because a controller can be exercised with a stubbed provider rather than a live dependency. The caveat is in the same place as the feature. The future plans list an IOC mechanism and a Module decorator as work still to be done, so the container today is a specific design rather than the full inversion of control model that NestJS users may picture.

## The database and the async choice are made at scaffold time

The application generator takes options that decide the shape of the project before you write code. The app name is required through the --app-name or -n flag. The database type is optional and you can specify PostgreSQL, MySQL, SQLite or MongoDB through the --db-type or -db flag. There is also an --is-async flag, documented as optional with a default of False, which decides whether the project is asynchronous. The documentation shows the combined form for a PostgreSQL project with an async connection:

```bash
pynest generate application -n my_app_name -db postgresql --is-async
```

The dependency extras in pyproject.toml mirror those choices. A postgres extra pulls in sqlalchemy, asyncpg, psycopg2, alembic, greenlet and python-dotenv, while a mongo extra brings in beanie and python-dotenv, and a test extra adds pytest. The repository examples make the same matrix visible on disk, with BlankApp, CommandLineApp, MongoApp, OrmAsyncApp and OrmSyncApp directories under examples/, plus a guard_examples.py file. Since the choice is baked into the scaffold, changing your mind later means editing the generated project rather than rerunning the generator.

## WebSocket gateways registered as providers

Real-time support is built on FastAPI's own WebSocket support rather than a separate abstraction. PyNest supports native FastAPI WebSocket gateways for real-time APIs, and the documentation describes the wiring: gateways are registered as providers, they participate in dependency injection, and they can use event handlers, lifecycle hooks, guards, rooms and token streaming patterns. Rooms and token streaming are the two capabilities that go beyond what a plain FastAPI WebSocket route gives you, and they are the ones worth checking first if you are building something with many concurrent clients. Guards are the other piece with a visible example, in the guard_examples.py file in the examples directory, which suggests the framework has a notion of request guards comparable to the ones NestJS applications use for authorization.

## The roadmap shows exactly what is not there yet

The future plans list is the most useful part of the documentation for an adopter, because it names the gaps rather than hinting at them. The open items are a plugins marketplace where developers can share and download modules, an IOC mechanism together with a Module decorator, support for additional databases, an out-of-the-box authentication module that can be integrated into any application, support for other testing frameworks along with testing templates, and support for other web frameworks such as Litestar and blackship, described as the same architecture with a different engine. Two of those change what you can build today. The missing auth module means every project writes its own, and the incomplete IOC mechanism means the dependency injection story is present but not the full NestJS container. The multi-framework plan is the most interesting long term signal, since it implies the architecture is meant to sit above the web framework rather than inside FastAPI alone.

## MIT licence, version 0.6.2 and a uv based workflow

The package is MIT licensed, and the project is still pre-1.0. The version in pyproject.toml is 0.6.2, and the classifiers call it a Beta, Development Status 4. The release list shows v0.6.2 on 2026-05-28, v0.6.0 on 2026-05-10 and v0.5.0 on 2026-05-09, so the recent work has been concentrated in the 0.6 line, while the last push to the repository was on 2026-10-17 and the repository is not archived. Python 3.10 or newer is required. Development uses uv, and the documentation is explicit that uv.lock is intentionally ignored and not committed because this is a library project, which means your builds resolve dependencies fresh rather than from a pinned lock. The documented commands are short:

```bash
uv sync --no-dev --group test
uv run pytest tests
```

and the build path runs uv sync with the build group, uv build for the sdist and wheel, and twine check on the result. Documentation builds with the docs group and mkdocs build --clean, with mkdocs.yml at the root and the docs directory holding the site, published at pythonnest.github.io/PyNest.

## Conclusion

PyNest fits a team moving from a NestJS codebase to Python, or a backend or ML engineer who wants controller, service and model separation plus dependency injection without hand-wiring it onto FastAPI. It is not yet a fit for a service that needs a pluggable auth module or a finished IOC container, because the framework lists both as future plans. Verify first that your generated project starts on the FastAPI version PyNest pins, that the injector based dependency wiring covers the cases you need, and that the uv sync --no-dev --group test flow runs in your environment, since the repository intentionally does not commit uv.lock.

## FAQ

### How do I create a new PyNest project?

Install the package with pip install pynest-api, then run pynest generate application -n my_app_name. The generator writes app.py, main.py, requirements.txt, a .gitignore, a README.md and a src package, and you start it with uvicorn "app:app" --host "0.0.0.0" --port "8000" --reload.

### How do I add a new module to a PyNest application?

Run pynest generate resource -n users. That creates a users folder under src with a controller, service, model, entity and module file, and the documentation states that the module registers itself with the application immediately.

### Which databases can PyNest scaffold for?

The application generator accepts a --db-type or -db option for PostgreSQL, MySQL, SQLite and MongoDB. An --is-async flag controls whether the project uses asynchronous connections, and the pyproject.toml extras named postgres and mongo carry the matching dependency sets.

### Does PyNest support WebSockets?

Yes. It supports native FastAPI WebSocket gateways, registered as providers that take part in dependency injection, and the documentation says they can use event handlers, lifecycle hooks, guards, rooms and token streaming patterns.

### Is PyNest a port of NestJS to Python?

No. The documentation states it is not a direct port but a re-imagining of the framework for Python developers, including backend and ML engineers, built on top of FastAPI.

## Sources

- [License: MIT](https://github.com/PythonNest/PyNest/blob/main/LICENSE)
- [Project website](https://pythonnest.github.io/PyNest)
- [PythonNest/PyNest on GitHub](https://github.com/PythonNest/PyNest)
- [README](https://github.com/PythonNest/PyNest/blob/main/README.md)
- [Releases](https://github.com/PythonNest/PyNest/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pythonnest-pynest