StephenBrown2: Definitely, I've added the param to the api spec, but the docs could use a larger fleshing out/update most likely.
sethmlarson: Yeah that'll be a pre-1.0 release probably. 
sethmlarson: Looks like CI is failing a few tests, take a look at those. 
StephenBrown2: Good catch, forgot what object I was in, fixed now.
StephenBrown2: Sure thing. Do we also want tests for cookies sent from the client since it's a similar use case?
sethmlarson: I added a single test-case that verifies the way that conflicting headers are resolved so we maintain that property of how they've resolved. :)
diff --git a/docs/api.md b/docs/api.md
index 1c6887c..dbc3d52 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -20,7 +20,7 @@
 >>> response = client.get('https://example.org')
 ```
 
-* `def __init__([auth], [cookies], [verify], [cert], [timeout], [pool_limits], [max_redirects], [app], [dispatch])`
+* `def __init__([auth], [headers], [cookies], [verify], [cert], [timeout], [pool_limits], [max_redirects], [app], [dispatch])`
 * `def .get(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
 * `def .options(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
 * `def .head(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout])`
diff --git a/httpx/client.py b/httpx/client.py
index 7bf759a..60088c2 100644
--- a/httpx/client.py
+++ b/httpx/client.py
@@ -49,6 +49,7 @@ class BaseClient:
     def __init__(
         self,
         auth: AuthTypes = None,
+        headers: HeaderTypes = None,
         cookies: CookieTypes = None,
         verify: VerifyTypes = True,
         cert: CertTypes = None,
@@ -95,6 +96,7 @@ class BaseClient:
             self.base_url = URL(base_url)
 
         self.auth = auth
+        self.headers = Headers(headers)
         self.cookies = Cookies(cookies)
         self.max_redirects = max_redirects
         self.dispatch = async_dispatch
@@ -109,6 +111,15 @@ class BaseClient:
             return merged_cookies
         return cookies
 
+    def merge_headers(
+        self, headers: HeaderTypes = None
+    ) -> typing.Optional[HeaderTypes]:
+        if headers or self.headers:
+            merged_headers = Headers(self.headers)
+            merged_headers.update(headers)
+            return merged_headers
+        return headers
+
     async def send(
         self,
         request: AsyncRequest,
@@ -527,6 +538,7 @@ class AsyncClient(BaseClient):
         timeout: TimeoutTypes = None,
     ) -> AsyncResponse:
         url = self.base_url.join(url)
+        headers = self.merge_headers(headers)
         cookies = self.merge_cookies(cookies)
         request = AsyncRequest(
             method,
@@ -608,6 +620,7 @@ class Client(BaseClient):
         timeout: TimeoutTypes = None,
     ) -> Response:
         url = self.base_url.join(url)
+        headers = self.merge_headers(headers)
         cookies = self.merge_cookies(cookies)
         request = AsyncRequest(
             method,
diff --git a/httpx/models.py b/httpx/models.py
index 2f29be5..bea47fa 100644
--- a/httpx/models.py
+++ b/httpx/models.py
@@ -415,6 +415,11 @@ class Headers(typing.MutableMapping[str, str]):
             split_values.extend([item.strip() for item in value.split(",")])
         return split_values
 
+    def update(self, headers: HeaderTypes = None) -> None:  # type: ignore
+        headers = Headers(headers)
+        for header in headers:
+            self[header] = headers[header]
+
     def __getitem__(self, key: str) -> str:
         """
         Return a single header value.

Set Headers like Cookies in Client session for all requests
Assuming one can use `Client`/`AsyncClient` as a drop-in replacement for `requests.Session`, I would like to be able to set headers (and cookies) to be sent for each request, for example for token-based authentication.

With `requests`, I can do:
```python
header_dict = {"X-Auth-Token": "FooBarBazToken"}
session = requests.Session()
session.headers.update(header_dict)
```

`cookies` can already be set on the `httpx.Client`. I would like to be able to also do that with `headers`:
```python
>>> headers = Headers({"X-Auth-Token": "FooBarBazToken", "User-Agent": "python-myclient/0.2.1"})
>>> session = Client(base_url="https://httpbin.org", headers=headers)

>>> get_headers = session.get("/headers")

>>> get_headers.json()
{'headers': {'Accept': '*/*',
  'Accept-Encoding': 'gzip, deflate',
  'Cookie': 'MyCookie=MyValue',
  'Host': 'httpbin.org',
  'User-Agent': 'python-myclient/0.2.1',
  'X-Auth-Token': 'FooBarBazToken'}}
```
diff --git a/tests/client/test_headers.py b/tests/client/test_headers.py
new file mode 100755
index 0000000..bf82a57
--- /dev/null
+++ b/tests/client/test_headers.py
@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+
+import json
+from httpx import (
+    __version__,
+    Client,
+    AsyncRequest,
+    AsyncResponse,
+    VerifyTypes,
+    CertTypes,
+    TimeoutTypes,
+    AsyncDispatcher,
+)
+
+
+class MockDispatch(AsyncDispatcher):
+    async def send(
+        self,
+        request: AsyncRequest,
+        verify: VerifyTypes = None,
+        cert: CertTypes = None,
+        timeout: TimeoutTypes = None,
+    ) -> AsyncResponse:
+        if request.url.path.startswith("/echo_headers"):
+            request_headers = dict(request.headers.items())
+            body = json.dumps({"headers": request_headers}).encode()
+            return AsyncResponse(200, content=body, request=request)
+
+
+def test_client_header():
+    """
+    Set a header in the Client.
+    """
+    url = "http://example.org/echo_headers"
+    headers = {"Example-Header": "example-value"}
+
+    with Client(dispatch=MockDispatch(), headers=headers) as client:
+        response = client.get(url)
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "headers": {
+            "accept": "*/*",
+            "accept-encoding": "gzip, deflate, br",
+            "connection": "keep-alive",
+            "example-header": "example-value",
+            "host": "example.org",
+            "user-agent": f"python-httpx/{__version__}",
+        }
+    }
+
+
+def test_header_merge():
+    url = "http://example.org/echo_headers"
+    client_headers = {"User-Agent": "python-myclient/0.2.1"}
+    request_headers = {"X-Auth-Token": "FooBarBazToken"}
+    with Client(dispatch=MockDispatch(), headers=client_headers) as client:
+        response = client.get(url, headers=request_headers)
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "headers": {
+            "accept": "*/*",
+            "accept-encoding": "gzip, deflate, br",
+            "connection": "keep-alive",
+            "host": "example.org",
+            "user-agent": "python-myclient/0.2.1",
+            "x-auth-token": "FooBarBazToken",
+        }
+    }
+
+
+def test_header_merge_conflicting_headers():
+    url = "http://example.org/echo_headers"
+    client_headers = {"X-Auth-Token": "FooBar"}
+    request_headers = {"X-Auth-Token": "BazToken"}
+    with Client(dispatch=MockDispatch(), headers=client_headers) as client:
+        response = client.get(url, headers=request_headers)
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "headers": {
+            "accept": "*/*",
+            "accept-encoding": "gzip, deflate, br",
+            "connection": "keep-alive",
+            "host": "example.org",
+            "user-agent": f"python-httpx/{__version__}",
+            "x-auth-token": "BazToken",
+        }
+    }
+
+
+def test_header_update():
+    url = "http://example.org/echo_headers"
+    with Client(dispatch=MockDispatch()) as client:
+        first_response = client.get(url)
+        client.headers.update(
+            {"User-Agent": "python-myclient/0.2.1", "Another-Header": "AThing"}
+        )
+        second_response = client.get(url)
+
+    assert first_response.status_code == 200
+    assert first_response.json() == {
+        "headers": {
+            "accept": "*/*",
+            "accept-encoding": "gzip, deflate, br",
+            "connection": "keep-alive",
+            "host": "example.org",
+            "user-agent": f"python-httpx/{__version__}",
+        }
+    }
+
+    assert second_response.status_code == 200
+    assert second_response.json() == {
+        "headers": {
+            "accept": "*/*",
+            "accept-encoding": "gzip, deflate, br",
+            "another-header": "AThing",
+            "connection": "keep-alive",
+            "host": "example.org",
+            "user-agent": "python-myclient/0.2.1",
+        }
+    }

pip install -e .
parse_log_pytest
requirements.txt
3.9
requirements.txt
pytest --no-header -rA --tb=line --color=no -p no:cacheprovider -W ignore::DeprecationWarning
attrs==25.3.0
autoflake==2.3.1
babel==2.17.0
backrefs==5.8
black==25.1.0
brotlipy==0.7.0
certifi==2025.1.31
cffi==1.17.1
chardet==3.0.4
charset-normalizer==3.4.1
click==8.1.8
colorama==0.4.6
coverage==7.8.0
cryptography==44.0.2
exceptiongroup==1.2.2
flake8==7.2.0
flake8-bugbear==24.12.12
flake8-comprehensions==3.16.0
ghp-import==2.1.0
h11==0.8.1
h2==3.2.0
hpack==3.0.0
hstspreload==2025.1.1
-e git+https://github.com/encode/httpx.git@3ba2e8c328f05b07ee06ae40f99dce7fe1e8292c#egg=httpx
hyperframe==5.2.0
idna==2.10
importlib_metadata==8.6.1
iniconfig==2.1.0
isort==6.0.1
Jinja2==3.1.6
Markdown==3.7
MarkupSafe==3.0.2
mccabe==0.7.0
mergedeep==1.3.4
mkdocs==1.6.1
mkdocs-get-deps==0.2.0
mkdocs-material==9.6.10
mkdocs-material-extensions==1.3.1
mypy==1.15.0
mypy-extensions==1.0.0
packaging==24.2
paginate==0.5.7
pathspec==0.12.1
platformdirs==4.3.7
pluggy==1.5.0
pycodestyle==2.13.0
pycparser==2.22
pyflakes==3.3.2
Pygments==2.19.1
pymdown-extensions==10.14.3
pytest==8.3.5
pytest-asyncio==0.26.0
pytest-cov==6.0.0
python-dateutil==2.9.0.post0
PyYAML==6.0.2
pyyaml_env_tag==0.1
requests==2.32.3
rfc3986==1.5.0
six==1.17.0
tomli==2.2.1
trustme==1.2.1
typing_extensions==4.13.0
urllib3==2.3.0
uvicorn==0.34.0
watchdog==6.0.0
zipp==3.21.0

name: httpx
channels:
  - defaults
  - https://repo.anaconda.com/pkgs/main
  - https://repo.anaconda.com/pkgs/r
  - conda-forge
dependencies:
  - _libgcc_mutex=0.1=main
  - _openmp_mutex=5.1=1_gnu
  - ca-certificates=2025.2.25=h06a4308_0
  - ld_impl_linux-64=2.40=h12ee557_0
  - libffi=3.4.4=h6a678d5_1
  - libgcc-ng=11.2.0=h1234567_1
  - libgomp=11.2.0=h1234567_1
  - libstdcxx-ng=11.2.0=h1234567_1
  - ncurses=6.4=h6a678d5_0
  - openssl=3.0.16=h5eee18b_0
  - pip=25.0=py39h06a4308_0
  - python=3.9.21=he870216_1
  - readline=8.2=h5eee18b_0
  - setuptools=75.8.0=py39h06a4308_0
  - sqlite=3.45.3=h5eee18b_0
  - tk=8.6.14=h39e8969_0
  - tzdata=2025a=h04d1e81_0
  - wheel=0.45.1=py39h06a4308_0
  - xz=5.6.4=h5eee18b_1
  - zlib=1.2.13=h5eee18b_1
  - pip:
      - attrs==25.3.0
      - autoflake==2.3.1
      - babel==2.17.0
      - backrefs==5.8
      - black==25.1.0
      - brotlipy==0.7.0
      - certifi==2025.1.31
      - cffi==1.17.1
      - chardet==3.0.4
      - charset-normalizer==3.4.1
      - click==8.1.8
      - colorama==0.4.6
      - coverage==7.8.0
      - cryptography==44.0.2
      - exceptiongroup==1.2.2
      - flake8==7.2.0
      - flake8-bugbear==24.12.12
      - flake8-comprehensions==3.16.0
      - ghp-import==2.1.0
      - h11==0.8.1
      - h2==3.2.0
      - hpack==3.0.0
      - hstspreload==2025.1.1
      - hyperframe==5.2.0
      - idna==2.10
      - importlib-metadata==8.6.1
      - iniconfig==2.1.0
      - isort==6.0.1
      - jinja2==3.1.6
      - markdown==3.7
      - markupsafe==3.0.2
      - mccabe==0.7.0
      - mergedeep==1.3.4
      - mkdocs==1.6.1
      - mkdocs-get-deps==0.2.0
      - mkdocs-material==9.6.10
      - mkdocs-material-extensions==1.3.1
      - mypy==1.15.0
      - mypy-extensions==1.0.0
      - packaging==24.2
      - paginate==0.5.7
      - pathspec==0.12.1
      - platformdirs==4.3.7
      - pluggy==1.5.0
      - pycodestyle==2.13.0
      - pycparser==2.22
      - pyflakes==3.3.2
      - pygments==2.19.1
      - pymdown-extensions==10.14.3
      - pytest==8.3.5
      - pytest-asyncio==0.26.0
      - pytest-cov==6.0.0
      - python-dateutil==2.9.0.post0
      - pyyaml==6.0.2
      - pyyaml-env-tag==0.1
      - requests==2.32.3
      - rfc3986==1.5.0
      - six==1.17.0
      - tomli==2.2.1
      - trustme==1.2.1
      - typing-extensions==4.13.0
      - urllib3==2.3.0
      - uvicorn==0.34.0
      - watchdog==6.0.0
      - zipp==3.21.0
prefix: /opt/conda/envs/httpx

tests/client/test_headers.py::test_client_header tests/client/test_headers.py::test_header_merge tests/client/test_headers.py::test_header_merge_conflicting_headers tests/client/test_headers.py::test_header_update
docs/api.md httpx/models.py httpx/client.py
docs/api.md httpx/models.py httpx/client.py