My 2025 uv-based Python Project Layout for Production Apps
Getting from a working Python script to an application humming along in production can be frustrating if you don't know where to start. And historically, it's been one of the most infamous Python pain points. But the good news is that over the run of 2024, Python's packaging and project tooling got infinitely better and faster.
So if you suffer from slow and tedious local workflows, updating log files taking minutes, maintaining separate log files for Linux, Windows, and Mac, writing three pages of setup instructions for new team members that somehow include also common Python compilation problems, or if you simply don't even know why your project is set up the way it is set up, this video is for you. Because local workflows can be ergonomic and robust now. Yes, really, with Python. And shipping Python applications using Docker containers really fast with safe, reproducible builds is a solved problem in 2025. Hello, internet. I'm Hynek. And I'm not just theorizing here. I'm responsible for the Python application infrastructure at a boutique web hoster and domain registrar in Germany called Variomedia, the best web hoster and domain registrar in the German-speaking world. We've been running our Python applications in production since 2009. And I've spoken about
these topics many times, both at Python and DevOps conferences all around the world. And I can tell you, it's astonishing how much better the workflow and deployment story of Python applications has become over the past 12 months. So I will break down how we do this. But here's the twist. We are going to do it using only one tool. Not an unholy combination of pip,
virtualenv, three types of Python installers plus... No. Just UV. One tool from setting up the project or running it locally to packaging it up into a slim Docker container. But while UV is very friendly, we still have a lot of ground to cover, including many concepts. This is why I didn't produce a single three-hour-long video that everybody's asking me to do, but a three-part series of hopefully not three one-hour-long videos. In this video, I'll show you how I set up
my project such they are nice to work with, easy to pick up by others, and nice to ship to production later. In the next one, I'll talk about ergonomic and productive local workflows. That part will include some extra tools that complement UV nicely and that are not Python-specific. And finally, in the last part, I'll show you how to ship the whole thing using Docker containers to production. And if there's enough interest, I may also do a fourth part that talks about how I structure my way too many open source projects. But I'd like to stick with videos that people actually want to watch for a moment or two. The first two parts don't talk about Docker at all. But many things that we will do will pay off later when packaging the app into a container.
So if you don't care about Docker but want nice local workflows, keep watching. The first two videos are for you. If you only care about Docker, subscribe so you don't miss the third episode. What I won't talk ever about is using Docker locally for development because it's such a terrible development experience compared to what's possible with local tooling nowadays. Even with the magic of Orbstack that y'all should really use if you're on macOS.
Then I'd rather become a goat farmer in the mountains than dealing with that. I do use Docker locally to run some obscure services on my notebook but not for my own code. And Cthulhu helped me for that never to change. But since I will be talking a lot about UV, here's a super quick refresher for those who missed the big Python packaging revolution of 2024. So UV is a tool written in Rust which makes it blazingly fast and whose ambition is to be the only tool you need to handle packaging related tasks in Python. Similarly to Rust's cargo or Node's NPM. It appeared pretty much exactly a year ago in February of 2024 and for many people it already has lived up to the ambition. In some ways it has even surpassed its role models. I've already made
two videos about UV. One asking whether it's the future of Python packaging shortly after it came out and one answering my own question six months later which if you haven't guessed it is yes. And if you haven't heard of UV before feel free to watch them first because I won't spend more time on regurgitating topics I've already covered and I can wait. I'm just a ghost of a dude caught on a video file. As for Astral's ambition, if you already ship Python applications in Docker containers
and got your way doing that without some special Conda features it is the only tool you need. And to prove it to you we'll go together step by step from a single Python file to a production-ready Docker container over the next three videos. Obviously these videos are optionated and obviously you don't have to apply everything one-to-one that I say but I'll explain why I do the things the way I do them to great success and it's up to you to decide if you want to follow suit or not. Personally I find pseudo-objective or unbiased content where people talk in theoretical terms about things they've never used themselves in anger rather unhelpful and I prefer contextualized earned opinions. But now let's write some Python because before we can package something it needs to exist. And it needs to exist in a shape that Python and its tools understand. And since Colombian of the year 2024 Sebastián Ramírez bought me breakfast the other today I'm gonna use the simplest example from FastAPI's documentation as the example project. It's literally just five
lines of code that say "hello world" but it comes with a shit ton of dependencies. And to be clear it does not matter what framework we're using here. I have no FastAPI in production myself. What's important here is that we are building a runnable Python application that has dependencies. Those dependencies could just as well have been Django or Flask or Polaris. And to be also clear we could use `uv init` to bootstrap the project and it would give us a reasonable skeleton project. But I want you to understand every step and setting we do. So we do it manually uphill both
ways. Now when setting up a Python application you have to make one decision right away. Are you going to make a proper Python package ideally within an unimportable src directory or an adhoc directory that usually works but sometimes requires PYTHONPATH shenanigans and other clutchy workarounds. There is no shame in going adhoc. The current implementation of PyPI which is called warehouse uses that layout. But I'm gonna be a model Python citizen and show you how
to do it properly because it tightens the envelope of possible states and shapes that my project can be in which simplifies import logic greatly. It's like easier to reason about this whole thing. It allows me to have proper CLI commands that I can call from the shell. I'm old school I like that. And it allows me to use packaging-only affordances like importlib in my code. And finally I can use `uv sync` to install both the application and its dependencies into the container. My simple mind likes consistency and symmetry just like you like me punching the microphone. Of course there's more reasons some of them being more vibe- based but I'll have to leave them for a future video so subscribe to not miss it. But I honestly think that the prevalence of adhoc design in the Python
ecosystem is just that Python's packaging tooling used to be a trash fire around 2010 – the formative years – and people did anything necessary to avoid interacting with it and are just doing whatever they're always done or whatever they see around the internet. I don't know I think in the age of UV it's time to reconsider. Either way this is how our Python project looks like if we make it a package. I've named the app hello-svc because it's a web service that says hello. I've named the file containing the web views views.py because it contains web views. The dunder init file is empty and marks the directory as an package. I've also put the package into an unimportable src directory to make sure that when I run tests against the package the tests imports only pick up code that is part of the package and guaranteed to be installed and not imported accidentally because they're laying around. This catches a whole category of packaging and installation
bugs and if you want to know more about this pattern I've written a blog post about it 10 short years ago and I'll link it in the description. Speaking of tests why not add some FastAPI comes with a handy test helper called TestClient and we'll define a pytest test fixture that creates it and write a test that uses it. I name my pytest fixture functions with an underscore and set their name explicitly to avoid the confusing error of forgetting to declare dependency in a test and accidentally using the function object as the fixture. All our test does is sending a get request to the web view and checking whether the response is 200 and the JSON response is correct. Simple but it happens to give us 100% test coverage which happens to be the only correct test coverage. I'll call the test file test e2e because it's end to end for certain definitions of end to end and since this is my video I get to decide on all definitions. Therefore our project
now looks like this and we are almost ready to run it but I'm gonna take this scenic route and talk about entry points for a moment. Boundaries between systems are extremely important to contain complexity. Entry points allow you to interact with such a system across boundaries in a controlled way. The narrower and better defined an entry point the easier it is to reason about the interactions with the system and the better the containment of the complexity. And this is true for any type of system. This is true for classes, this is true for modules, and this is true for your application.
Now we want to run an asynchronous web application and for that we need a web application framework, in this case FastAPI, but we also need a server that handles the whole networking part and forwards web requests to the framework that in turn forwards them to your application. And to make the server interoperable between web frameworks there's a standard how async web frameworks and their servers interact and it's the asynchronous server gateway interface or short ASGI. So when running an asynchronous web application you use a web framework to create the application conventionally called app. And in our case it's an instance of the fast API class that is also used to register the web view. The tutorial does this by pointing the server directly at the views.py module but I'm not a fan of like randomly groping into packages. I like to have clear standardized entry points into my applications whose only job is to bridge between the dirty real world and my pristine application. These entry points are leaf modules. They never get imported except
for the purpose of running the application. They contain code that must only be run once like loading configuration, setting a global state like logging or configuring at exit cleanup handlers. That makes them about the hardest to test – so I don't. And this is the only module where you have
my blessing to add it to coverage's `omit` list. And to mitigate the risk this introduces I keep them as simple as possible with no loops or if statements so I have a reasonable amount of certainty that if my application comes up in dev it will also come up in prod given I test all other parts of the system. And bigger apps also tend to have more than one entry point. Sometimes you have CLI entry points or job queue workers like RQ or Dramatiq or Celery that also need entry points into your applications. And in that case I group those entry points in a separate directory
that I call… entry points. And all that's a lot of words to say for an ASGI based application I create a module called asgi.py and do everything needed to set up the application in there. In our case it's just importing the app object from views.py. Again in a real life application you
would configure logging, setup crash reporting and whatnot in this module. And to give you just a taste here's an example of a wsgi.py. WSGI being the classic synchronous web standard that we use to run Flask applications. Most of this is not super exciting except for the surprise cameo of my environ-config of course. But you can see it's using the application factory pattern with a twist that it doesn't just return a WSGI application like it usually does in all the examples but it also returns a cleanup function that we register to be run when the application exits. That's where we close our database connections for example. And this atexit handler may be registered only once. But I can run the factory and its respective cleanup as often as I
want because they don't perform any global state changes. And I do that in fact very often because I have a test fixture like this in my test which gives me a fresh application object for each test and cleans up behind it too. So I hope this detour was indeed scenic and let's get back to our application which now looks like this. And now we know on one side that we just have to point our ASGI container whether it's the FastAPI dev server or uvcorn or hypercorn or granian or whatever to the asgi.py module to run the application. And the good news is that we are now done writing Python. The bad news is that we can neither run our development server nor the tests just yet. We have to add a tiny bit of metadata about our project so Python and the tools know
what is what. And in modern python projects and by modern I mean still maintained after the year of the plague you do that in a file called pyproject.toml. And toml if you haven't heard of it yet is a simple configuration file format just keys equals value. It's very similar to the venerable INI file format but it allows for things like lists. And as of Python 3.11 we even have a toml parser as part of the standard library called tomlib to make handling those files easier.
So let's start with the simple stuff that belongs into the general project category. First a project needs a name and we've already settled on hello-svc. And don't let the dash instead of an underscore confuse you it's just part of the package name normalization. You can write it both ways but internally it will be normalized to dashes. And usually if your normalized directory name matches your normalized package name you don't have to tell packaging where to find the code. It's smart enough to find it even if it's hidden inside of an src directory. A python
package also needs a version but since this is an application that is eventually shipped to a server we don't care about package versions and we can set it to zero and never touch it again. Next we have to decide what python version we'd like our app to run under and we set it using requires-python. You can set a pretty complex rule here as specified by PEP 440 to limit the ranges of valid python versions. But again we are shipping an application to a server so we need only one version and that's in our case 3.13. And I find this syntax the most obvious one instead of some weird carets or tildes but use whatever you prefer. Conveniently many modern tools like Black or Ruff will also interpret this standardized field so you do not have to tell them the minimum version separately anymore. UV will go a step further still. After determining the python
version to use it will happily download a standalone build of it for you from GitHub if it can't find it on your computer and unless forbidden to do so. Since this video is about packaging using UV only end-to-end we will take advantage of this feature later. But let's not get ahead of ourselves and specify what our application needs to run. In our case we need FastAPI and since we want to greet the world at web scale we also depend on granian an asgi container written in rust – which makes it blazingly fast – that is used to actually run the application. There's others like uvicorn and hypercorn but I had to pick one so i'm sticking with the rust theme and that's all we need in production. Oh wait! Since nobody watched my last video let's add stamina for good measure and if you want to know what it's about make sure to check out my last video on proper retries. The
shilling will continue until views improve. Locally we have a bit different needs. For one we want to be able to run our tests and maybe we want to use FastAPI's development server instead of a boring serious business production service since it comes with quality of life features like auto reloads and cute emoji. Very important. And FastAPI has a packaging extra just for that called standard. So what we want to do is tell uv to install pytest and FastAPI with the `standard` extra – but only in development. And to achieve that the python packaging authority gave us the gift
of dependency groups in PEP 735 that Astral promptly implemented in uv. It allows us to define groups of optional dependencies that are installed on demand and if you call one of the groups dev it's automatically installed by uv unless explicitly told to not do that. So that's exactly what we are gonna do. I need to stress that dependency groups are not the same thing as packaging extras like the standard in a FastAPI dependency. They are a separate concept and notably are not stored as part of the packaging metadata because they are explicitly not part of packaging writ large. So you can even use them when your application is not a package. Therefore this is
great for package maintainers that are annoyed that it looks like our packages depend on pytest or sphinx because their development extras leak into PyPI. We are just waiting for pip to ship support too, for that global nightmare to be finally over. Now please note that at this point so far we have used zero uv specific settings or features. We've only used standard python packaging settings. Everything so far should work whether you use uv or not. And this will change now because we finally specify how our application package should be built by specifying build dependencies and a build backend. Usually you'd put something like setuptools here but i promised to only use uv. So we are gonna use a super secret preview feature instead. We'll even have to set
an environment variable for this to work. So don't tell anybody. But we are done with pyproject.toml. This is all it takes in a year of 2025 to create a package-based python application. No setup.py, no arcane options nobody understands anymore but copies around just in case, no misappropriation of packaging features and our project now looks like this. But how do we even use this? We haven't run uv a single time yet. So if you're following along this is the time to install uv or making sure that it's up to date. I'll wait. And now we just type uv run pytest, press enter and they pass. You can run uv run fast api dev src hello service asg.py and the development
server comes up and you can curl it right away. What's that? You had no python installed? Or just ancient legacy versions like 3.12? No problemo. uv took care of that. It knows what python versions you want after all. Thanks to the python requires metadata and the Astral team having taken over the
python standalone build project to make this possible. You wanted to create a virtual end first so it doesn't pollute your global site packages? Sorry, uv was faster than you. You know, rust and all. It automatically creates a virtualenv called .venv in a project directory. And if it exists but has the wrong version of python in it, it just recreates it. Oh, but you wanted to lock your dependencies recursively so you can go make a coffee and such that random package updates don't break your deployment because complaining on open source projects about changes breaking your production is very bad karma and shows that you don't have your dependencies under control? Check your pocket, your project directory again. See that uv.lock file? uv created automatically when you ran `uv run` for the first time and installed dependencies into a virtualenv.
And how fast? As long as you stick with running your commands using uv run, it will also always make sure your virtualenv has all the correct packages in the correct versions installed. So if you git pull and your co-worker added or updated some dependencies, `uv run` will notice that and install or update the dependencies before running. And the log file is even a cross-platform log file, which means that you can use the same log file on your ARM Mac notebook and on your intel linux server. A feature that you might never see as an official standard due to this idiot. Sorry, Brett. But we don't need no stinking standards because we can now run `uv run pytest` and `uv run fastapi` without any preparations except installing uv. And this is the true magic of uv.
You've installed one static binary that will never break that you've run only once and it ran your test suite and it started the local web server under a second. And unless you've explicitly told uv to do things in non-standard ways, there's almost no room for error from your side. It's essentially foolproof, which is my favorite kind of proof. You just have to remember to check in uv.lock and to git-ignore .venv. And anybody who is not ugly crying tears of joy right now never had
to onboard someone to a non-trivial python project. So finally, our project directory looks like this. And congratulations, you have a properly packaged python application. You have recursively locked dependencies for repeatable builds and stable deployments. And you've got a foolproof way to run commands in its environment with the correct python version and dependencies. That means we are done for today. But this is not good enough for me. So before we go on to package this app into our docker container, we'll spend some time making this environment more developer friendly. Because this is where we live day to day. And I promise no arcane shell scripts or make
files will be involved. So make sure to subscribe so you don't miss it. Yes, this video took way too long again. One of the reasons is the complete disaster that my last video was and the motivational hole I had to dig myself out. And the other is that the project ballooned in scope that I had to split up in the end. Like originally, I only wanted to do the third part because uv and docker is currently my most popular blog post. Link in description if you need help right now. But I
kept adding things that I find important and that people just keep asking me about. So I've somehow become George R.R. Martin. But I solemnly swear that it's just three parts and will be out before the Winds of Winter. But even though I've split the video in three parts, there's still too many
topics to zoom in on all of them. So if you'd like a more verbose explanation of any of the concepts I've mentioned in passing, hit the comments and let me know. I'm still niche enough to read all comments. And this video series is a result of popular demand to after all, maybe I'll even do some kind of q&a video at the very end. I mean, this channel is still very much in its experimental phase. So there are no rules. If you want to learn more about what I do and also get some background information on my videos and how I feel about this whole damn thing, you should check out my newsletter that you can also read by RSS if you hate email, I tried to add a cute photo of my occasional foster dog Barnaby. And the last edition contained a look
back on the first year of YouTube. And you can find in the archive too if you don't want to subscribe. I'm not trying to hide anything from anyone. Now looking briefly into the future, this spring is going to be bananas for me for completely accidental reasons. I'll be traveling most of March, go to PyTexas in April and finally be speaking at PyCon US in May. So let's
see when I'll get to write that talk. Anyhow, if you see me in Taiwan, the Philippines or at any of the PyCons, come and say hi. It's always great to meet fans. It feels weird to say fans. As always, all my work would not be possible without my amazing GitHub sponsors. So thank you, thank you, thank you to my employer Variomedia and of course, its customers, Tidelift, Klaviyo, FilePreviews, emsys, Privacy Solutions and Ecosystems. And special thanks also go out to
Daniel Fortunov and Kevin P. Fleming. And of course, everybody who's still choosing to support me in these trying times. I feel it too. It sucks. Your support means everything to me. And with that, thanks to everyone who watches all the way to the end. You're the best. And I hope you'll enjoy a Python a little bit more still.
2025-03-02 08:15
