Using the Standalone Installer

The uv project provides a standalone installer that you can use to download and install the tool in your system. Below are the relevant commands for the three main operating systems:

• Windows
• Linux + macOS

PS>powershell-ExecutionPolicyByPass-c"irm https://astral.sh/uv/install.ps1 | iex"

$curl-LsSfhttps://astral.sh/uv/install.sh|sh

$wget-qO-https://astral.sh/uv/install.sh|sh

These commands will download and install the latest binary of uv in your system. If you’d like to install a specific version of the tool instead of the latest, then you can add the version number to the download URL right after theuv/ part:

• Windows
• Linux + macOS

https://astral.sh/uv/0.6.12/install.ps1

https://astral.sh/uv/0.6.12/install.sh

With this addition to the download URL, you request the installation of uv version0.6.12. Once you’ve downloaded and installed uv with the appropriate command, you can verify the installation by running the following command:

$uv--versionuv 0.6.12 (e4e03833f 2025-04-02)

Now you’re all set up with uv. In this case, you’re using version0.6.12. Of course, your specific version may differ slightly depending on when you read this tutorial.

You can run theuv --help command at any time to display the help page, which provides detailed information about each command and option the tool offers. Go ahead and give it a try!

Installing From PyPI

You can also install uv from thePython Package Index (PyPI) usingpipx. As with the standalone installer, the uvcommand-line-interface (CLI) will be available globally on your system.

To install uv usingpipx, run the following command:

$pipxinstalluv

Note that for this command to work, you needpipx to be available in your environment. This involves an extra step. If you don’t want to install an additional app, then you can usepip, which is typically shipped by default with most Python distributions.

However, to have system-wide access to uv, you’ll have to install it in your Python system installation. This isn’t recommended because it could clutter your system with packages that you may not use.

Upgrading to the Latest uv Version

As you know, time flies. The uv project is currently under active development, which means that new versions are released regularly.

If you’ve installed uv using thestandalone installer and would like to be up to date with the latest version, then you can run the following command:

$uvselfupdateinfo: Checking for updates...success: Upgraded uv from v0.6.10 to v0.6.12!⮑ https://github.com/astral-sh/uv/releases/tag/0.6.12

Theuv self update command checks whether a new version is available. If that’s the case, the command downloads the new package and installs it for you.

If you’ve installed uv withpipx and want to upgrade it, then you can run the command below:

$pipxupgradeuv

This command allows you to upgrade your uv installation to the latest version if you usedpipx.

Creating a Python Project

To create and initialize a Python project with uv, navigate to the directory where you want to store the project. Once there, you can run the following command to create and initialize the project:

$uvinitrpcats

Note that the project name is up to you. In this example, you’ll userpcats to denote that this is a Real Python project for retrieving and displaying information about cats.

The command above creates the following directory structure under therpcats/ folder:

rpcats/│├── .git/│├── .gitignore├── .python-version├── README.md├── main.py└── pyproject.toml

This is cool! First, you have the.git/ directory, which is the Git repository for your project. The.gitignore file allows you to define the files and folders you want to skip in your version control workflow. By default, uv automatically populates this file with sensible entries for most Python projects, ensuring that unwanted files are excluded from version control.

The.python-version file contains the default Python version for the current project. This file tells uv which Python version to use when creating a dedicated virtual environment for the project. Next, you have an emptyREADME.md file that you can use to provide basic documentation for your project.

Themain.py file is a placeholder Python file that initially contains the following code:

defmain():print("Hello from rpcats!")if__name__=="__main__":main()

In this case, you have amain() function that prints a message to the screen. At the bottom of the file, you have the well-knownif __name__ == "__main__" idiom, which is common practice in executable files like this one.

Finally, you have thepyproject.toml file with the following initial content:

[project]name="rpcats"version="0.1.0"description="Add your description here"readme="README.md"requires-python=">=3.13"dependencies=[]

This file contains basic configuration key-value pairs under the[project] table. You can update the value of any key to meet your requirements. For example, you can change thedescription to something like the following:

[project]name="rpcats"version="0.1.0"description="Display cat information for the specified breed."readme="README.md"requires-python=">=3.13"dependencies=[]

Now, your project has a concrete description. You could also change the project’s version, the required Python version, and so on.

$uvinit

That’s it! You’ve created your first project with uv. Now you can run the project’s entry-point script,main.py, to check that everything’s working correctly.

Running the Project’s Entry-Point Script

Once you’ve created the project, you can use uv to run the entry-point script, which is themain.py file by default. To run the script, go ahead and execute the following command:

$uvrunmain.pyUsing CPython 3.13.2Creating virtual environment at: .venvHello from rpcats!

The first time you run this command, it’ll display the Python version you’re currently using for the project. It’ll also inform you that uv has created a dedicated Python virtual environment for the project. The final output line shows the message that results from calling themain() function defined inmain.py.

If you check the content of your project’s root directory again, then you’ll find a.venv folder containing the dedicated virtual environment. You’ll also find a new file calleduv.lock, which is a cross-platformlockfile that contains information about your project’s dependencies. This file ensures that other developers can quickly and exactly reproduce your working environment. This enhances team collaboration and code contributions.

Unlikepyproject.toml, which usually specifies the direct dependencies of your project, theuv.lock file contains the exact versions of any dependency installed in the project environment.

Theuv.lock file uses theTOML format. You should add this file to version control. However, you shouldn’t edit this file manually. Instead, you can let uv take care of it. You’ll learn more about this file in a moment.

Adding and Installing Dependencies

Now, go back to the beginning of theHandling Python Projects With uv section, expand the collapsible block, and copy the code for the sample CLI app. Paste the code into themain.py file in your project’s root folder.

Once you have the code in place, you might be tempted to run the app with a command like the following:

$uvrunmain.pyPersianTraceback (most recent call last):    ...ModuleNotFoundError: No module named 'requests'

The app fails with aModuleNotFoundError exception. Why? Because you haven’t installed the required dependencies in your working environment.

In your cat app example, you need theRequests library, which is a popular library for making HTTP requests in Python. You use this library to retrieve cat information from the Cat API.

Go ahead and run the following command to make uv addrequests:

$uvaddrequests

This command lets you add the Requests library to your project’s dependencies. It also installs the library in your project’s virtual environment. Once it finishes running, go ahead and check the content of yourpyproject.toml file:

[project]name="rpcats"version="0.1.0"description="Display cat information for the specified breed."readme="README.md"requires-python=">=3.13"dependencies=["requests>=2.32.3",]

Notice howuv add automatically updates your list of dependencies by addingrequests to thepyproject.toml file. In this case, the installed version should be greater or equal to2.32.3.

$uvadd-rrequirements.txt

Internally,uv add also updates theuv.lock file with version information for the following:

• Direct dependencies: Packages that your project depends on directly. For example, your cat app depends onrequests.
• Transitive dependencies: Packages that support your project’s direct dependencies. For example, the Requests library depends onurllib3, and you get it installed as a transitive dependency.

You don’t have to worry about theuv.lock content and shouldn’t edit it yourself. Instead, let uv be in charge of it. However, you must version-control it.

As you can conclude,uv add does the dependency management work for you. It installs the dependencies, edits thepyproject.toml file if necessary, and keeps theuv.lock file up-to-date. This ensures that other developers can reproduce your working environment.

Would you like to give your cat app another try? Go ahead and run it:

$uvrunmain.pyPersian-----------Persian------------Origin: Iran (Persia)Temperament: Affectionate, Loyal, Sedate, QuietLife Span: 14 - 15 yearsWeight: 9 - 14 lbsLearn more: https://en.wikipedia.org/wiki/Persian_(cat)

Now, your cat app is working correctly. It makes API requests, processes the responses, and displays information for the target breed of cat.

Upgrading and Removing Dependencies

You can also use uv to update and remove dependencies. For example, say that some time has passed since you released the latest version of yourrpcats app, and you’d like to continue the development by adding new features. However, you realize a new version is available for the Requests library.

In this situation, you can use the following command to upgraderequests:

$uvadd--upgraderequests

This command upgradesrequests and updates its version information in theuv.lock file. This action allows you to work with the library’s latest version and ensures that other developers can do the same.

If you decide at any point that your project doesn’t need a dependency anymore, then you can remove it with the following command:

$uvremove<package_name>

For example, if you’d like yourrpcats app to check for multiple cats at once, you might want to use a library likeaiohttp, which is capable of makingasync HTTP requests. In that case, you can removerequests and addaiohttp.

It’s important to note thatuv remove also removes transitive dependencies and updates thepyproject.toml anduv.lock files accordingly.

Managing Development Dependencies

In most development environments, you’ll have dependencies that aren’t required for running the code but are vital for developing it. For example, testing libraries likepytest, code formatters like Ruff, and static type checkers likemypy might be some of these development dependencies.

You can use uv to manage these types of dependencies. This time, you’ll use theuv add command with the--dev flag. For example, say that you want to write tests for the cats app. To do this, you want to usepytest. Because your project doesn’t need this library to run, you can install it as a development dependency:

$uvadd--devpytest

This command will installpytest in your project’s virtual environment and add the library as a development dependency to yourpyproject.toml anduv.lock files.

If you check the content ofpyproject.toml after running the command above, then you’ll find the following:

[project]name="rpcats"version="0.1.0"description="Display cat information for the specified breed."readme="README.md"requires-python=">=3.13"dependencies=["requests>=2.32.3",][dependency-groups]dev=["pytest>=8.3.5",]

The highlighted lines show how uv automatically updated the file to includepytest in your list of development dependencies. You can also check the content ofuv.lock if you want to confirm thatpytest is there as well.

Now you can write the tests for your projects!

Locking and Syncing the Environment

As you’ve already learned, uv uses theuv.lock file to lock a project’s dependencies.Locking consists of capturing your project’s specific dependencies in the lockfile. This process makes it possible to reproduce your working environment in all possible configurations, including the Python version and distribution, the operating system, and the architecture.

As a counterpart,syncing is the process of installing the required packages from the lockfile into the project’s development environment.

Both locking and syncing processes are automatically handled by uv. For example, when you executeuv run, the project is locked and synced before the command is invoked. This behavior ensures that your project’s environment is always up to date.

Now, imagine that you’ve pulled the cat app from a GitHub repository and would like to try it. In this scenario, you’ll only have the source code and the uv configuration files. You won’t have a proper Python virtual environment with the required dependencies to run the app.

To reproduce this situation, you can go ahead and remove the.venv/ folder from the project’s root directory. Then, let uv do the hard work for you:

$uvrunmain.py"Scottish Fold"Using CPython 3.13.2Creating virtual environment at: .venvInstalled 9 packages in 53ms--------Scottish Fold---------Origin: United KingdomTemperament: Affectionate, Intelligent, Loyal, Playful, Social, Sweet, LovingLife Span: 11 - 14 yearsWeight: 5 - 11 lbsLearn more: https://en.wikipedia.org/wiki/Scottish_Fold

As you can see, before trying to execute the app, uv creates a dedicated virtual environment at the.venv/ directory. Then, it installs the dependencies and finally runs the app.

To make sure that uv has reproduced the environment correctly, you can run the following command:

$uvpiplistPackage            Version------------------ ---------certifi            2025.1.31charset-normalizer 3.4.1idna               3.10iniconfig          2.1.0packaging          24.2pluggy             1.5.0pytest             8.3.5requests           2.32.3urllib3            2.3.0

This is the list of packages installed in the project’s virtual environment and their specific versions. You can compare this list with the content of theuv.lock file. The packages and versions will coincide, which ensures the exact reproduction of the original development environment.

Finally, you can explicitly lock and sync your project with the following commands:

$uvlock$uvsync

These commands are helpful if you encounter issues with running the project and want to ensure that you’re using the correct version of each dependency.

Configuring the Project

Your cat app has a command-line interface (CLI), so you need to explicitly set the project’s entry-point script so that the build system can properly set up the executable file for the app. Go to thepyproject.toml file and add the following:

[project]name="rpcats"version="0.1.0"description="Display cat information for the specified breed."readme="README.md"requires-python=">=3.13"dependencies=["requests>=2.32.3",][dependency-groups]dev=["pytest>=8.3.5",][project.scripts]rpcats="main:main"

With these two additional lines, you ensure that when someone installs your app, they can run therpcats command from their terminal to execute the code from themain() function, which is stored in themain.py file.

Next, you need to define a build system. In this tutorial, you’ll useSetuptools as the build system. Go ahead and add the following lines to the end of yourpyproject.toml file:

[project]name="rpcats"version="0.1.0"description="Display cat information for the specified breed."readme="README.md"requires-python=">=3.13"dependencies=["requests>=2.32.3",][dependency-groups]dev=["pytest>=8.3.5",][project.scripts]rpcats="main:main"[build-system]requires=["setuptools>=78.1.0","wheel>=0.45.1"]build-backend="setuptools.build_meta"

The first highlighted line specifies that the build system will requiresetuptools andwheel. The second highlighted line defines the build backend. With these two additions to theproject.toml file, you’re ready to build a distribution for your app.

Building a Distribution

You can use theuv build command to build source and binary distributions for your Python project. By default,uv build will build the project and place the distributions in adist/ subdirectory under the project’s root:

$uvbuildBuilding source distribution...running egg_infocreating rpcats.egg-info...Successfully built dist/rpcats-0.1.0.tar.gzSuccessfully built dist/rpcats-0.1.0-py3-none-any.whl

When you type in theuv build command and pressEnter, the building process starts. You’ll see a detailed output on your terminal screen. At the end of the output, you’ll get a message telling you that the package has been successfully built.

You also have the following build options:

• uv build --sdist
• uv build --wheel

The first command builds asource distribution only, while the second command builds abinary distribution. Note that usinguv build without any flags will build both the source and binary distributions.

Publishing a Distribution

The final step is to publish the built package to a package repository like PyPI so that your users can download and install it on their systems.

Beforepublishing a package to PyPI, you should make sure that everything works correctly. To this end, you can publish your package to theTestPyPI index, which is a special repository designed for testing purposes. You’ll need to set up anaccount in TestPyPI and generate anAPI token. Once you’ve done that, you can manually edit yourpyproject.toml file as shown below:

[project]name="rpcats"version="0.1.0"description="Display cat information for the specified breed."readme="README.md"requires-python=">=3.13"dependencies=["requests>=2.32.3",][dependency-groups]dev=["pytest>=8.3.5",][project.scripts]rpcats="main:main"[build-system]requires=["setuptools>=78.1.0","wheel>=0.45.1"]build-backend="setuptools.build_meta"[[tool.uv.index]]name="testpypi"url="https://test.pypi.org/simple/"publish-url="https://test.pypi.org/legacy/"explicit=true

With these additions, you set up a custom index calledtestpypi. You must also change thename key to something unique that doesn’t exist in TestPyPI. Otherwise, you won’t be able to upload the package because the name already exists.

Now, you can useuv publish with the--index option to upload your app to TestPyPI:

$uvpublish--indextestpypi--tokenyour_token_here

To run this command, you’ll need to add your personal API token for TestPyPI following the--token option. Once you’ve entered all the information, pressEnter to upload the app to TestPyPI. That should be it!

To try the app, you’ll create a new virtual environment in a different directory. So, go ahead and open a terminal window in any other directory on your hard drive. Then, run the following commands:

$uvvenvUsing CPython 3.13.2Creating virtual environment at: .venvActivate with: source .venv/bin/activate$uvpipinstall-ihttps://test.pypi.org/simple/rpcats  × No solution found when resolving dependencies:  ╰─▶ Because only requests==2.5.4.1 is available and rpcats==0.1.0 depends on      requests>=2.32.3, we can conclude that rpcats==0.1.0 cannot be used.      And because only rpcats==0.1.0 is available and you require rpcats, we      can conclude that your requirements are unsatisfiable.

With theuv venv command, you create a fresh virtual environment in your working directory under the.venv folder.

Next, you try to installrpcats from TestPyPI using the-i option ofuv pip. The installation fails because uv is trying to install arequests version greater than or equal to2.32.3, as your dependencies state. However, the latestrequests version in TestPyPI is2.5.4.1, which doesn’t fulfill your needs.

To work around this issue, you can installrequests from PyPI and then installrpcats as before:

$uvpipinstallrequests$uvpipinstall-ihttps://test.pypi.org/simple/rpcats$uvrunrpcatsPersian-----------Persian------------Origin: Iran (Persia)Temperament: Affectionate, Loyal, Sedate, QuietLife Span: 14 - 15 yearsWeight: 9 - 14 lbsLearn more: https://en.wikipedia.org/wiki/Persian_(cat)

Here, you manually install Requests from PyPI. Next, you installrpcats from TestPyPI with the same command as before. Finally, you runrpcats with theuv run command to make sure it works properly. Note that you’re not runningmain.py, butrpcats as a command instead.

Once you’re sure your project works correctly, you can upload it to PyPI’s main index. Again, you need to have anaccount and an API token.

Once you have the account and the token at hand, run the following command to publish your package:

$uvpublish--tokenyour_token_here

This command uses PyPI as its default package index. As with TestPyPI, you need to enter yourAPI token. Once the command is done, your app will be available in PyPI, and you’ll be able to install it like any other Python package.