The 5 Minute Streamlit Project Setup with uv

Using Astral’s uv has been a timesaver! Instead of manually having to setup Git and my virtual environment, uv does it all for me. So here’s how to do it step by step or feel free to watch the Youtube video at the end.

How to setup uv

1. Create a new local directory and open it in VSCode.

   • Open a terminal window in VSCode (Windows hotkey: Ctrl + ` ).

2. Make a new directory to store your program: mkdir your-project-name

3. Go into the new directory: cd your-project-name

4. Install uv (https://docs.astral.sh/uv/). Make sure this is done in a Python environment that's in your system's $PATH. Otherwise, you won't be able to run uv in the terminal.

5. Run uv init in the terminal. A bunch of files should be automatically added to the directory, and git is initialised.

6. To see all the files in your directory, including the hidden ones, you should see all the files that uv added your git repository files/directory and your README file, use: ls -a

   • uv should have added your git repository

7. Add the files to the repository: git add .

   • You should not see the .env file or the virtual environment directory .venv in the list of files and directories that Git will add to the repository, because uv has already added those to the .gitignore file!

8. Commit this state as an initial commit in git, and publish to Github.

   • Commit it: git commit -m "Initial commit"

   • Check the git status again and then look at the git log to see your first commit: git log

     • You should see the message with the commit id, author and date with the commit message:

       commit 65b992794c181fbf065eabe682a58de46adf3c89
       Author: Your Name <yourname@somedomain.com>
       Date:   Sat Jul 19 11:02:03 2025 -0700
       
           Initial commit
       

   • The repo will need to be public in order for it to be deployed to Streamlit Community Cloud. Or you can keep it private to deploy to Render.

   • If you create the repo via Github, initialise it empty (without a README file, for example), because uv should have added this file.

9. Activate it your virtual environment:

   • Mac: source .venv/bin/activate

   • PC: .venv\Scripts\activate

   • You should see your command line prompt change to have some like the following: (.venv) your path %

10. Run main.py in terminal using the command uv run main.py.

    • This should create the environment using uv, including the creation of a .venv subdirectory (containing a newly created vitual environment for your project) and a uv.lock file in the root directory (which specifies your project's dependencies).

11. Add streamlit to your virtual environment by running uv add streamlit in the terminal. Streamlit and its dependencies should all be added to the virtual environment, the pyproject.toml file and the uv.lock file. You can install other dependencies in this way as well (just like using pip install).

12. Check that everthing is working by:

    1. Modifying main.py to use streamlit

import streamlit as st

def main():
    st.header("Hello from your-project!")

if __name__ == "__main__":
    main()

1. Activating the virtual environment in terminal by running .venv\Scripts\activate.

2. Running main.py using streamlit in the terminal with the command streamlit run main.py. The streamlit app should launch in you browser and display as expected.

3. To stop running the app, use Ctrl + C in the terminal. This will allow you to continue running other commands in terminal (you will have to close the browser manually though).

Watch the video instead

https://youtu.be/gf4LhKlogII

In my next article, I’ll detail how to set up your repo as a Python package to make it easier to organize your code.

References

• https://github.com/data-sloth/uv-streamlit-setup/tree/main