Creating a Project With uv

00:00 Now that you’ve installed uv, you want to create a project with it using the commands or rather the subcommands uv init. And when you’re working with uv, what you’ll find is that regardless of whether you are managing a project like we will be in this video course or doing something else, you’ll essentially be living inside the CLI interface that uv provides.

00:21 So uv provides many different subcommands, and you’re going to learn some. And it’s through these subcommands that you perform uv actions, and uv init will initialize a project.

00:33 So you can go ahead and open your terminal.

00:37 And once you are in your terminal, make sure you’re inside a folder where you’re okay with creating projects with uv and playing around with uv.

00:46 And you’ll want to run the command uv init. Now the command uv init expects the name of your project as an argument. And so for a reason that will become obvious in a couple of lessons because of the example code you will be using, you’ll want to name these first project rpcats for Real Python Cats.

01:06 So you press Enter and you get a message saying that uv initialized the project rpcats at the given location that you chose. And if you ls inside your current directory, you will see this folder where uv created your project.

01:23 So go ahead and cd into the folder rpcats.

01:28 Now if you list the contents of this folder with ls -al, you will see a number of folders and files that uv created for you. You can see the .git directory and the .gitignore file.

01:42 And these files are here because uv assumes you will be using some version control system and therefore, it initializes a Git repository and it adds a .gitignore file that already ignores some files that are useful to ignore in Python projects.

01:59 To see what I mean, if you use the command cats to take a look at the file .gitignore by running cat .gitignore, you can see at the very, not the first line, but at the second line of the file, you can find the __pycache__/ folder.

02:13 So this .gitignore file is already ignoring your __pycache__/ folder and its contents. Now go ahead. Let’s clear the screen for the sake of clarity and list everything again. Another file you can see that uv created for you is the .python-version file.

02:28 Now this is a very simple file that contains a single line of content. If you use the command cat to take a look at the file .python-version, you will see a number, in this case, 3.13.

02:42 What this means is that the default Python version for the project is 3.13. For you, this might be a different number. This will depend on your uv settings, the global uv settings, it’ll depend on whether or not you specify a different Python version.

03:00 The Python version you use by default with uv, it’s going to depend on a number of factors. By default, in my case, I got 3.13, but know that you can also change this with a specific flag when you’re running uv init.

03:15 Now another file that uv created for you is the file main.py. And this file is just a Python stub file that contains a couple of lines of code that you can use to check that the project was set up correctly.

03:30 But that doesn’t really implement any fancy functionality. It just contains a call to a print() function inside the function main().

03:38 And then a check to verify if you’re running the file directly with the if __name__ == "__main__":. So if you don’t know what the if __name__ == "__main__": is doing, Real Python has a nice tutorial explaining what this is.

03:51 So this is just a stub file where you will be able to write your Python code, or you can just delete it and write your Python code elsewhere. It’s just there to help you get started.

04:02 And finally, there are two other files. Well, there’s the README.md, and this is fairly standard. It’s your standard README file where you will want to have some basic instructions, maybe the high-level overview of what your project is.

04:16 It’s maybe also a good place to insert some basic commands to get people coming to your projects started or up to speed with what your project does. So this is the file that is typically shown if you open your project on GitHub or when folks download your project, they will often start by reading what’s in the README file.

04:39 So that’s why you want some basic instructions there. And finally, I skipped over this file. There’s the pyproject.toml file. So let me go ahead, clear the screen and let’s use cats to inspect what this file contains.

04:54 Now this TOML file contains configuration values for your projects. You can see that right now uv already populated some information in your pyproject.toml file.

05:08 The very first line contains the word project inside the square brackets. And this is a TOML header and it’s specifying, let’s call it a section of key-value pairs.

05:20 And this project section is the standard section where you will have metadata about your project. You can see the name of your project, you can see the version of your project, a description that you can edit, and a requirement on the Python version that this project depends on.

05:39 Again, these were populated by uv. You can edit your pyproject.toml file by hand if you know what you’re doing. There’s lots of different things that can go in this file, and some other uv subcommands will also edit this file automatically.

05:54 So this file is partially managed by uv.

05:59 That’s it for the files that uv creates as soon as you initialize the project. And in the next lesson, you’ll learn about a very useful uv subcommand that lets you run your projects or run the code of your project.

06:14 And you’ll also see what files uv will create because of that subcommand.