Python environments: venv, Conda, and Docker

Back to Resources

Start with venv. Follow a project’s existing setup if it already gives clear instructions. Do not combine all three tools for a simple project.

Python: start with a virtual environment

An environment keeps one project’s packages separate from other projects. Use venv for a normal Python project. Use the Python version required by the project; check its README first.

1. Install Python

Install Python from python.org. Open a new terminal after installation. On Windows, check that this command works:

python --version

If Windows cannot find Python, try py --version. Use py instead of python for the environment creation command below.

2. Create and use .venv

Open the project folder in the VS Code terminal. On Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

On macOS or Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

If PowerShell blocks Activate.ps1, use the environment’s Python directly. You do not need to change the computer’s script policy:

.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe hello.py

Select this same environment in VS Code. Python’s venv guide.

3. Install project packages and check your environment

If the project has a requirements.txt, run:

python -m pip install -r requirements.txt
python -c "import sys; print(sys.executable)"

The printed path must point inside .venv. If you did not activate the environment, replace python with the full environment Python path shown above.

For a new practice project, install two common data packages and save the tested versions. Run this only in your new environment; keep an existing project’s package file unchanged.

python -m pip install numpy pandas
python -m pip freeze > requirements.txt

Create hello.py with print("My Python environment works"). Run python hello.py. The terminal must print that message.

For a real project, install only the packages that you need. Record the tested package versions in requirements.txt. Follow the existing project file if it uses pyproject.toml or another package tool. Do not replace that setup with a second package system.

Add these lines to .gitignore if they are missing:

.venv/
__pycache__/
.ipynb_checkpoints/
.env

Commit your source code and package file. Do not commit .venv, passwords, access tokens, or private data. Recreate the environment on another computer instead of copying its folder. Run deactivate when you finish. Python packaging guide.

Conda: use it when the project needs it

Conda manages Python versions and packages. Use this route if the project gives you an environment.yml, or asks for Conda. Do not activate Conda and .venv together.

1. Install a Conda distribution from the official Conda installation guide.
2. Open its terminal. For a new example environment, run:

conda create --name lab-python python=3.12
conda activate lab-python
python --version

1. If the project provides environment.yml, create its environment instead:

conda env create --file environment.yml

1. Activate the name written in that file. Select it in VS Code.
2. Install packages from the project’s instructions. Keep the environment separate from Conda’s base environment.
3. For a new Conda project, install its packages and save the environment:

conda install numpy pandas
conda env export --from-history > environment.yml

1. Open environment.yml. Remove a computer-specific prefix: line if one appears. Keep the name, channels, and package list. Commit this file with your code. This records your chosen packages; use the project’s tested lock file too when exact versions are required.
2. Run conda deactivate when you finish.

If PowerShell does not know conda, use the installed Conda terminal first. Follow the official shell setup before using it in another terminal. Manage Conda environments.

Docker: run a project in a container

A container runs an application with its system tools and packages. Use Docker when a project needs a shared system setup. Start with venv if you only need Python packages. What Docker does.

1. Install and check Docker

Install Docker Desktop. On Windows, follow its Windows installation steps and WSL 2 requirements. Start Docker Desktop, wait until the engine is ready, and run:

docker version
docker run --rm hello-world

2. Run one simple Python file

Use a new practice folder. Save this file as hello.py:

print("Python is running inside Docker")

In the same folder, create a file named Dockerfile, with no file extension:

FROM python:3.12-slim
WORKDIR /app
COPY hello.py .
CMD ["python", "hello.py"]

Build and run it:

docker build -t lab-python-demo .
docker run --rm lab-python-demo

The dot in the build command means the current folder. After you edit hello.py, build the image again before you run it. This example prints a message and exits; it does not save research results. Use the project’s documented data folders and mounts for real work. Dockerfile reference.

For an existing project, read its Dockerfile, compose.yaml, and README first. Keep secrets and private data out of the image. Use the project’s .dockerignore to exclude local environments, .git, and private files.